Collections | API Reference

List

get

/collections

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

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

Authorizations

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

Complete collection representation returned by the API.

This schema includes all collection metadata plus computed status information based on the health and state of associated source connections.

namestringRequired

Human-readable display name for the collection.

descriptionany ofOptional

Description of the collection.

stringOptional

or

nullOptional

colorany ofOptional

Color for the collection.

stringOptional

or

nullOptional

iconany ofOptional

Icon for the collection.

stringOptional

or

nullOptional

readable_idstringRequired

URL-safe unique identifier used in API endpoints. This becomes non-optional once the collection is created.

idstring · uuidRequired

Unique system identifier for the collection. This UUID is generated automatically and used for internal references.

vector_sizeintegerRequired

Vector dimensions used by this collection. Determines which embedding model is used: 3072 (text-embedding-3-large), 1536 (text-embedding-3-small), or 384 (MiniLM-L6-v2).

embedding_model_namestringRequired

Name of the embedding model used for this collection (e.g., 'text-embedding-3-large', 'text-embedding-3-small'). This ensures queries use the same model as the indexed data.

created_atstring · date-timeRequired

Timestamp when the collection was created (ISO 8601 format).

modified_atstring · date-timeRequired

Timestamp when the collection was last modified (ISO 8601 format).

organization_idstring · uuidRequired

Identifier of the organization that owns this collection. Collections are isolated per organization.

created_by_emailany ofOptional

Email address of the user who created this collection.

string · emailOptional

or

nullOptional

modified_by_emailany ofOptional

Email address of the user who last modified this collection.

string · emailOptional

or

nullOptional

statusstring · enumOptional

Current operational status of the collection:• NEEDS_SOURCE: Collection has no authenticated connections, or connections exist but haven't synced yet• ACTIVE: At least one connection has completed a sync or is currently syncing• ERROR: All connections have failed their last sync

Default: NEEDS SOURCEPossible values:

422

Validation Error

application/json

get

/collections

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

/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

x-api-keystringRequired

Organization API key for authentication

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Body

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

Complete collection representation returned by the API.

This schema includes all collection metadata plus computed status information based on the health and state of associated source connections.

namestringRequired

Human-readable display name for the collection.

descriptionany ofOptional

Description of the collection.

stringOptional

or

nullOptional

colorany ofOptional

Color for the collection.

stringOptional

or

nullOptional

iconany ofOptional

Icon for the collection.

stringOptional

or

nullOptional

readable_idstringRequired

URL-safe unique identifier used in API endpoints. This becomes non-optional once the collection is created.

idstring · uuidRequired

Unique system identifier for the collection. This UUID is generated automatically and used for internal references.

vector_sizeintegerRequired

Vector dimensions used by this collection. Determines which embedding model is used: 3072 (text-embedding-3-large), 1536 (text-embedding-3-small), or 384 (MiniLM-L6-v2).

embedding_model_namestringRequired

Name of the embedding model used for this collection (e.g., 'text-embedding-3-large', 'text-embedding-3-small'). This ensures queries use the same model as the indexed data.

created_atstring · date-timeRequired

Timestamp when the collection was created (ISO 8601 format).

modified_atstring · date-timeRequired

Timestamp when the collection was last modified (ISO 8601 format).

organization_idstring · uuidRequired

Identifier of the organization that owns this collection. Collections are isolated per organization.

created_by_emailany ofOptional

Email address of the user who created this collection.

string · emailOptional

or

nullOptional

modified_by_emailany ofOptional

Email address of the user who last modified this collection.

string · emailOptional

or

nullOptional

statusstring · enumOptional

Current operational status of the collection:• NEEDS_SOURCE: Collection has no authenticated connections, or connections exist but haven't synced yet• ACTIVE: At least one connection has completed a sync or is currently syncing• ERROR: All connections have failed their last sync

Default: NEEDS SOURCEPossible values:

422

Validation Error

application/json

post

/collections

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

/collections/{readable_id}

Retrieve a specific collection by its readable ID.

Authorizations

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

Complete collection representation returned by the API.

This schema includes all collection metadata plus computed status information based on the health and state of associated source connections.

namestringRequired

Human-readable display name for the collection.

descriptionany ofOptional

Description of the collection.

stringOptional

or

nullOptional

colorany ofOptional

Color for the collection.

stringOptional

or

nullOptional

iconany ofOptional

Icon for the collection.

stringOptional

or

nullOptional

readable_idstringRequired

URL-safe unique identifier used in API endpoints. This becomes non-optional once the collection is created.

idstring · uuidRequired

Unique system identifier for the collection. This UUID is generated automatically and used for internal references.

vector_sizeintegerRequired

Vector dimensions used by this collection. Determines which embedding model is used: 3072 (text-embedding-3-large), 1536 (text-embedding-3-small), or 384 (MiniLM-L6-v2).

embedding_model_namestringRequired

Name of the embedding model used for this collection (e.g., 'text-embedding-3-large', 'text-embedding-3-small'). This ensures queries use the same model as the indexed data.

created_atstring · date-timeRequired

Timestamp when the collection was created (ISO 8601 format).

modified_atstring · date-timeRequired

Timestamp when the collection was last modified (ISO 8601 format).

organization_idstring · uuidRequired

Identifier of the organization that owns this collection. Collections are isolated per organization.

created_by_emailany ofOptional

Email address of the user who created this collection.

string · emailOptional

or

nullOptional

modified_by_emailany ofOptional

Email address of the user who last modified this collection.

string · emailOptional

or

nullOptional

statusstring · enumOptional

Current operational status of the collection:• NEEDS_SOURCE: Collection has no authenticated connections, or connections exist but haven't synced yet• ACTIVE: At least one connection has completed a sync or is currently syncing• ERROR: All connections have failed their last sync

Default: NEEDS SOURCEPossible values:

422

Validation Error

application/json

get

/collections/{readable_id}

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

/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

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

Complete collection representation returned by the API.

This schema includes all collection metadata plus computed status information based on the health and state of associated source connections.

namestringRequired

Human-readable display name for the collection.

descriptionany ofOptional

Description of the collection.

stringOptional

or

nullOptional

colorany ofOptional

Color for the collection.

stringOptional

or

nullOptional

iconany ofOptional

Icon for the collection.

stringOptional

or

nullOptional

readable_idstringRequired

URL-safe unique identifier used in API endpoints. This becomes non-optional once the collection is created.

idstring · uuidRequired

Unique system identifier for the collection. This UUID is generated automatically and used for internal references.

vector_sizeintegerRequired

Vector dimensions used by this collection. Determines which embedding model is used: 3072 (text-embedding-3-large), 1536 (text-embedding-3-small), or 384 (MiniLM-L6-v2).

embedding_model_namestringRequired

Name of the embedding model used for this collection (e.g., 'text-embedding-3-large', 'text-embedding-3-small'). This ensures queries use the same model as the indexed data.

created_atstring · date-timeRequired

Timestamp when the collection was created (ISO 8601 format).

modified_atstring · date-timeRequired

Timestamp when the collection was last modified (ISO 8601 format).

organization_idstring · uuidRequired

Identifier of the organization that owns this collection. Collections are isolated per organization.

created_by_emailany ofOptional

Email address of the user who created this collection.

string · emailOptional

or

nullOptional

modified_by_emailany ofOptional

Email address of the user who last modified this collection.

string · emailOptional

or

nullOptional

statusstring · enumOptional

Current operational status of the collection:• NEEDS_SOURCE: Collection has no authenticated connections, or connections exist but haven't synced yet• ACTIVE: At least one connection has completed a sync or is currently syncing• ERROR: All connections have failed their last sync

Default: NEEDS SOURCEPossible values:

422

Validation Error

application/json

delete

/collections/{readable_id}

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

/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

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

Individual sync job for a source connection.

idstring · uuidRequired

source_connection_idstring · uuidRequired

statusstring · enumRequired

Sync job status enum.

Possible values:

started_atany ofOptional

string · date-timeOptional

or

nullOptional

completed_atany ofOptional

string · date-timeOptional

or

nullOptional

duration_secondsany ofOptional

numberOptional

or

nullOptional

entities_insertedintegerOptionalDefault: 0

entities_updatedintegerOptionalDefault: 0

entities_deletedintegerOptionalDefault: 0

entities_failedintegerOptionalDefault: 0

errorany ofOptional

stringOptional

or

nullOptional

error_detailsany ofOptional

or

nullOptional

422

Validation Error

application/json

post

/collections/{readable_id}/refresh_all

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

/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

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

Legacy search response schema for backwards compatibility.

response_typestring · enumRequired

Indicates whether results are raw search matches or AI-generated completions

Possible values:

completionany ofOptional

AI-generated natural language answer when response_type is 'completion'

stringOptional

or

nullOptional

statusstring · enumRequired

Status of the search operation

Possible values:

422

Validation Error

application/json

get

/collections/{readable_id}/search

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

/collections/{readable_id}/search

Search your collection.

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

Authorizations

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

or

Responses

200

Successful Response

application/json

or

422

Validation Error

application/json

post

/collections/{readable_id}/search

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"
}

Good night

hashtagList

hashtagCreate

hashtagGet

hashtagDelete

hashtagRefresh All Source Connections

hashtagSearch Get Legacy

hashtagSearch

List

Create

Get

Delete

Refresh All Source Connections

Search Get Legacy

Search