Collections

API endpoints for managing collections - logical groups of data sources that provide unified search capabilities

List

get

https://api.graffo.iohttp://localhost:8001

/collections

List all collections that belong to your organization with optional search filtering.

Collections are always sorted by creation date (newest first).

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Query parameters

skipintegerOptional

Number of collections to skip for pagination

Default: 0

limitinteger · min: 1 · max: 1000Optional

Maximum number of collections to return (1-1000)

Default: 100

searchstringOptional

Search term to filter by name or readable_id

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/collections

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.collections.list()
print(resp)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Finance Data",
    "readable_id": "finance-data-ab123",
    "created_at": "2024-01-15T09:30:00Z",
    "modified_at": "2024-01-15T14:22:15Z",
    "organization_id": "org12345-6789-abcd-ef01-234567890abc",
    "created_by_email": "[email protected]",
    "modified_by_email": "[email protected]",
    "status": "ACTIVE"
  }
]

Create

post

https://api.graffo.iohttp://localhost:8001

/collections

Create a new collection.

Only organization owners and admins can create collections. The creator is automatically assigned as collection_owner.

The newly created collection is initially empty and does not contain any data until you explicitly add source connections to it.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Body

application/json

Schema for creating a new collection.

Collections serve as logical containers for organizing related data sources. Once created, you can add source connections to populate the collection with data from various sources like databases, APIs, and file systems.

namestring · min: 4 · max: 64Required

Human-readable display name for the collection. This appears in the UI and should clearly describe the data contained within (e.g., 'Finance Data').

Example: Finance Data

descriptionany ofOptional

Optional description of the collection to provide additional context.

Example: Quarterly financial reports and analytics

string · max: 500Optional

or

nullOptional

colorany ofOptional

Optional color for the collection (hex code, CSS color name, or RGB).

Example: #3b82f6

string · max: 50Optional

or

nullOptional

iconany ofOptional

Optional icon name or identifier for the collection.

Example: chart-line

string · max: 100Optional

or

nullOptional

readable_idany ofOptional

URL-safe unique identifier used in API endpoints. Must contain only lowercase letters, numbers, and hyphens. If not provided, it will be automatically generated from the collection name with a random suffix for uniqueness (e.g., 'finance-data-ab123').

Example: finance-data-ab123

stringOptionalPattern: ^[a-z0-9]+(-[a-z0-9]+)*$

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/collections

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.collections.create(
    name="My Collection",
    readable_id="readable_id",
)
print(resp)

{
  "color": "#3b82f6",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_email": "[email protected]",
  "description": "Financial reports and analytics collection",
  "icon": "chart-line",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "modified_at": "2024-01-15T14:22:15Z",
  "modified_by_email": "[email protected]",
  "name": "Finance Data",
  "organization_id": "org12345-6789-abcd-ef01-234567890abc",
  "readable_id": "finance-data-ab123",
  "status": "ACTIVE"
}

Get

get

https://api.graffo.iohttp://localhost:8001

/collections/{readable_id}

Retrieve a specific collection by its readable ID.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

readable_idstringRequired

The unique readable identifier of the collection (e.g., 'finance-data-ab123')

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/collections/{readable_id}

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.collections.get(readable_id="readable_id")
print(resp)

{
  "color": "#3b82f6",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_email": "[email protected]",
  "description": "Financial reports and analytics collection",
  "icon": "chart-line",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "modified_at": "2024-01-15T14:22:15Z",
  "modified_by_email": "[email protected]",
  "name": "Finance Data",
  "organization_id": "org12345-6789-abcd-ef01-234567890abc",
  "readable_id": "finance-data-ab123",
  "status": "ACTIVE"
}

Delete

delete

https://api.graffo.iohttp://localhost:8001

/collections/{readable_id}

Delete a collection and all associated data.

Only organization owners/admins and collection owners can delete collections.

Permanently removes a collection from your organization including all synced data from the destination systems. All source connections within this collection will also be deleted as part of the cleanup process. This action cannot be undone.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

readable_idstringRequired

The unique readable identifier of the collection to delete

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

delete

/collections/{readable_id}

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
client.collections.delete(readable_id="readable_id")

{
  "color": "#3b82f6",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by_email": "[email protected]",
  "description": "Financial reports and analytics collection",
  "icon": "chart-line",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "modified_at": "2024-01-15T14:22:15Z",
  "modified_by_email": "[email protected]",
  "name": "Finance Data",
  "organization_id": "org12345-6789-abcd-ef01-234567890abc",
  "readable_id": "finance-data-ab123",
  "status": "ACTIVE"
}

Refresh All Source Connections

post

https://api.graffo.iohttp://localhost:8001

/collections/{readable_id}/refresh_all

Trigger data synchronization for all source connections in the collection.

Only organization owners/admins, collection owners and collection editors can refresh collections.

The sync jobs run asynchronously in the background, so this endpoint returns immediately with job details that you can use to track progress. You can monitor the status of individual data synchronization using the source connection endpoints.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

readable_idstringRequired

The unique readable identifier of the collection to refresh

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/collections/{readable_id}/refresh_all

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
client.collections.refresh_all(readable_id="readable_id")

[
  {
    "source_connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "id": "987fcdeb-51a2-43d7-8f3e-1234567890ab",
    "organization_id": "org12345-6789-abcd-ef01-234567890abc",
    "created_by_email": "[email protected]",
    "modified_by_email": "[email protected]",
    "created_at": "2024-01-15T14:00:00Z",
    "modified_at": "2024-01-15T14:05:22Z",
    "status": "completed",
    "entities_inserted": 45,
    "entities_updated": 12,
    "entities_deleted": 3,
    "entities_kept": 234,
    "entities_skipped": 8,
    "entities_encountered": {
      "issues": 67,
      "pull_requests": 23,
      "commits": 156,
      "releases": 12,
      "readme_files": 8
    },
    "started_at": "2024-01-15T14:00:15Z",
    "completed_at": "2024-01-15T14:05:22Z"
  }
]

Deprecated

Search Get Legacy

get

https://api.graffo.iohttp://localhost:8001

/collections/{readable_id}/search

Legacy GET search endpoint for backwards compatibility.

DEPRECATED: This endpoint uses the old schema. Please migrate to POST with the new SearchRequest format for access to all features.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

readable_idstringRequired

The unique readable identifier of the collection to search

Query parameters

querystringRequired

The search query text to find relevant documents and data

response_typestring · enumOptional

Format of the response: 'raw' returns search results, 'completion' returns AI-generated answers

Default: rawPossible values:

limitinteger · min: 1 · max: 1000Optional

Maximum number of results to return

Default: 100

offsetintegerOptional

Number of results to skip for pagination

Default: 0

recency_biasany ofOptional

How much to weigh recency vs similarity (0..1)

number · max: 1Optional

or

nullOptional

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/collections/{readable_id}/search

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(
    base_url="https://api.graffo.io",
    api_key="YOUR_API_KEY",
    agent_key="YOUR_AGENT_KEY",  # opcional
)

resp = client._client_wrapper.httpx_client.request(
    method="GET",
    url=f"https://api.graffo.io/collections/{readable_id}/search",
    json={"...": "..."},  # ajusta el payload
)
print(resp.json())

{
  "results": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "response_type": "raw",
  "completion": "text",
  "status": "success"
}

Search

post

https://api.graffo.iohttp://localhost:8001

/collections/{readable_id}/search

Search your collection.

Accepts both new SearchRequest and legacy LegacySearchRequest formats for backwards compatibility.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

readable_idstringRequired

The unique readable identifier of the collection

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Body

application/json

or

Responses

200

Successful Response

application/json

Responseany of

or

422

Validation Error

application/json

post

/collections/{readable_id}/search

Python SDKTypeScript SDK

from graffo import GraffoSDK, SearchRequest

client = GraffoSDK(
    base_url="https://api.graffo.io",
    api_key="YOUR_API_KEY",
    agent_key="YOUR_AGENT_KEY",  # opcional
)

resp = client.collections.search(
    readable_id="readable_id",
    request=SearchRequest(query="query"),
)
print(resp)

{
  "results": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "completion": "text"
}