​
Prerequisites

1

Transfer Existing Source to Relace

Start by transferring your existing repositories to Relace.
import requests

url = "https://api.relace.run/v1/repo"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "source": {
        "type": "git",
        "url": "https://github.com/username/repository-name",
        "branch": "main"
    },
    "metadata": {...}  # Optional: add any custom properties
}

response = requests.post(url, headers=headers, json=data)
repo = response.json()
print(f"Repository created with ID: {repo['repo_id']}")
Keep track of the Relace repo_id in your database for future reference. You can optionally include a metadata parameter to add any properties of repos you want to maintain.If you have a lot of repos to transfer, you’ll have to perform this step in batches. See the policies section for information on rate limits.
2

Create New Relace Repos

For creating new repositories, we recommend using Relace Templates to minimize repo creation latency. However, you can also use the same functions above.
import requests

url = "https://api.relace.run/v1/repo"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "source": {
        "type": "relace",
        "repo_id": "your-template-repo-id",
    },
    "metadata": {...}  # Optional: add any custom properties
}

response = requests.post(url, headers=headers, json=data)
repo = response.json()
print(f"Repository created with ID: {repo['repo_id']}")
3

Integrate Repos with Your Agent

Now that your repositories live in Relace, you can integrate them with your agent’s local file system. You can fetch the stored files directly from our API without needing to setup git on your host:
import requests

url = f"https://api.relace.run/v1/repo/{repo_id}/clone"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
repo_files = response.json()

# The response contains all files with their content
for file in repo_files['files']:
    print(f"File: {file['filename']}")
    print(f"Content: {file['content'][:100]}...")  # First 100 characters
After your agent modifies files, push the changes back to Relace. You can either update specific files or overwrite all repository content.
import requests

# Apply specific file operations using diff mode
url = f"https://api.relace.run/v1/repo/{repo_id}/update"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "source": {
        "type": "diff",
        "operations": [
            {
                "type": "write",
                "filename": "src/main.py",
                "content": "def main():\n    print('Agent updated this function')\n    return True"
            },
            {
                "type": "rename",
                "old_filename": "src/helpers.ts"
                "new_filename": "src/utils.ts"
            },
            {
                "type": "delete",
                "filename": "old-unused-file.py"
            }
        ]
    }
}

response = requests.post(url, headers=headers, json=data)
print(f"Applied diff operations: {response.json()}")
4

Use Built-In Semantic Retrieval

Repositories stored in Relace get automatically indexed with our code embedding model and are refreshed with each code update. Use the retrieve endpoint as an agent tool to score files based on relevance to a user query.
import requests

url = f"https://api.relace.run/v1/repo/{repo_id}/retrieve"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "query": "Add a user profile component with avatar and edit functionality",
}

response = requests.post(url, headers=headers, json=data)
results = response.json()["results"]
You can parse the results the same way you do with direct calls to the reranker.
[
  {
    "filename": "src/components/UserProfile.tsx",
    "score": 0.9598
  },
  {
    "filename": "src/types/user.ts",
    "score": 0.0321
  },
  {
    "filename": "src/components/Header.tsx",
    "score": 0.0014
  }
]
For more details, see our API reference.