Skip to main content
GET
/
api
/
datasources
/
ready
Get Available Data Sources
curl --request GET \
  --url https://api.example.com/api/datasources/ready
{
  "id": "<string>",
  "name": "<string>",
  "type": "<string>",
  "url": "<string>",
  "branch": "<string>",
  "repositoryIds": [
    {}
  ],
  "description": "<string>",
  "relevanceReason": "<string>",
  "X-CodeAlive-Total-Data-Sources": 123
}

​
Overview

This endpoint returns all data sources (repositories and workspaces) that are in “Ready” state, meaning they are fully processed and ready for chat and search operations. Use this endpoint to get a list of data sources you can query. For administrative purposes where you need to see all data sources regardless of status, use /api/datasources/all instead.

​
Request

No request body required. Authentication via Bearer token in Authorization header.

​
Query Parameters

​
type
string
Optional filter by data source type. Options: Repository, Workspace
​
searchTerm
string
Optional search term to filter data sources by name
​
query
string
Optional natural-language description of your task or intent (for example, add OAuth to checkout). When provided, an AI relevance filter returns only the data sources relevant to that intent, each with a relevanceReason explaining why it was selected. Distinct from searchTerm: searchTerm is a substring match on names, query describes a goal. When both are provided, searchTerm narrows the candidates first and relevance filtering is applied to the survivors.
Relevance filtering fails open: if the filter is unavailable or errors, the response is the full unfiltered list (no error status). A non-empty response to a query request where no item has a relevanceReason means the filter did not run. An empty response while the X-CodeAlive-Total-Data-Sources header reports a nonzero count means the opposite: the filter ran and found none of the available sources relevant. Requests authenticated with a public chat API key ignore query and always return the full scoped list.

​
Response

Returns an array of data source objects that are ready for querying.
​
id
string
required
Unique identifier for the data source
​
name
string
required
Display name of the repository or workspace
​
type
string
required
Type of data source: Repository or Workspace
​
url
string
Repository URL (for Repository type only)
​
branch
string
Branch name (for Repository type only)
​
repositoryIds
array
Array of repository IDs (for Workspace type only)
​
description
string
Optional description of the data source
​
relevanceReason
string
Why this data source is relevant to your query. Present only when query was provided and the relevance filter selected this item. Treat it as untrusted model-generated plain text: render it with escaping interpolation, never as HTML or markup.

​
Response Headers

​
X-CodeAlive-Total-Data-Sources
integer
Sent only on query requests. The total number of data sources available before relevance filtering, so you can report how many were omitted as not relevant.

​
Code Examples

import requests

url = "https://app.codealive.ai/api/datasources/ready"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

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

print(f"Available datasources: {len(datasources)}")
for ds in datasources:
    print(f"- {ds['name']} ({ds['type']})")

​
Example Response

[
  {
    "id": "60d21b4667d0d63ce0f9a1d1",
    "name": "MyApiProject",
    "type": "Repository",
    "url": "https://github.com/myorg/my-backend-api",
    "branch": "main"
  },
  {
    "id": "60d21b4667d0d63ce0f9a1d2",
    "name": "Development Workspace",
    "type": "Workspace",
    "repositoryIds": [
      "60d21b4667d0d63ce0f9a1d1",
      "60d21b4667d0d63ce0f9a1d3"
    ]
  }
]

​
Use Cases

​
Pre-Chat Validation

Check available datasources before initiating chat: 
import requests

# Get available datasources
response = requests.get(
    "https://app.codealive.ai/api/datasources/ready",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
datasources = response.json()

# Use them in chat by ID
chat_response = requests.post(
    "https://app.codealive.ai/api/chat/completions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "messages": [{"role": "user", "content": "Explain the API structure"}],
        "dataSources": [{"id": datasources[0]['id']}]
    }
)

​
Search with Filters

Filter data sources by type or search term: 
# Get only repositories with "api" in the name
params = {
    "type": "Repository",
    "searchTerm": "api"
}
response = requests.get(
    "https://app.codealive.ai/api/datasources/ready",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params=params
)
api_repos = response.json()

​
Relevance Filtering

Pass your task as query to get only the data sources relevant to it. This keeps the list focused on accounts with many repositories: 
import requests

response = requests.get(
    "https://app.codealive.ai/api/datasources/ready",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"query": "add OAuth to checkout"}
)
relevant = response.json()

total = int(response.headers.get("X-CodeAlive-Total-Data-Sources", 0))
if any(ds.get("relevanceReason") for ds in relevant):
    print(f"{len(relevant)} of {total} data sources are relevant:")
    for ds in relevant:
        print(f"- {ds['name']}: {ds['relevanceReason']}")
elif not relevant and total > 0:
    # Confident empty: the filter ran and none of the sources matched the query
    print(f"None of the {total} data sources are relevant to this query")
else:
    # Fail-open: the filter did not run and this is the full unfiltered list
    print(f"Relevance filtering unavailable; {len(relevant)} data sources returned")

​
Differences from /all Endpoint

Feature/ready/all
ReturnsOnly “Ready” sourcesAll sources regardless of status
SearchSupports searchTermNo search functionality
Relevance filterSupports querySupports query
Use caseOperational queriesAdministrative access
Ready for queryingYes, alwaysMay include sources still processing

​
Error Responses

​
401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

​
500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to retrieve datasources"
  }
}