Collections
API endpoints for managing collections - logical groups of data sources that provide unified search capabilities
List all collections that belong to your organization with optional search filtering.
Collections are always sorted by creation date (newest first).
Organization API key for authentication
Number of collections to skip for pagination
0Maximum number of collections to return (1-1000)
100Search term to filter by name or readable_id
Successful Response
Validation Error
GET /collections HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*
[
{
"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 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.
Organization API key for authentication
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.
Human-readable display name for the collection. This appears in the UI and should clearly describe the data contained within (e.g., 'Finance Data').
Finance DataOptional description of the collection to provide additional context.
Quarterly financial reports and analyticsOptional color for the collection (hex code, CSS color name, or RGB).
#3b82f6Optional icon name or identifier for the collection.
chart-lineURL-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').
finance-data-ab123^[a-z0-9]+(-[a-z0-9]+)*$Successful Response
Validation Error
POST /collections HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 150
{
"color": "#10b981",
"description": "Financial reports and analytics data",
"icon": "chart-bar",
"name": "Finance Data",
"readable_id": "finance-data-reports"
}{
"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"
}Retrieve a specific collection by its readable ID.
Organization API key for authentication
The unique readable identifier of the collection (e.g., 'finance-data-ab123')
Successful Response
Validation Error
GET /collections/{readable_id} HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"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 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.
Organization API key for authentication
The unique readable identifier of the collection to delete
Successful Response
Validation Error
DELETE /collections/{readable_id} HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"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"
}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.
Organization API key for authentication
The unique readable identifier of the collection to refresh
Successful Response
Validation Error
POST /collections/{readable_id}/refresh_all HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*
[
{
"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"
}
]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.
Organization API key for authentication
The unique readable identifier of the collection to search
The search query text to find relevant documents and data
Format of the response: 'raw' returns search results, 'completion' returns AI-generated answers
rawPossible values: Maximum number of results to return
100Number of results to skip for pagination
0How much to weigh recency vs similarity (0..1)
Successful Response
Validation Error
GET /collections/{readable_id}/search?query=text HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"results": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"response_type": "raw",
"completion": "text",
"status": "success"
}Search your collection.
Accepts both new SearchRequest and legacy LegacySearchRequest formats for backwards compatibility.
Organization API key for authentication
The unique readable identifier of the collection
Successful Response
Validation Error
POST /collections/{readable_id}/search HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1497
{
"query": "text",
"context_cluster_ids": [
"text"
],
"retrieval_strategy": "hybrid",
"filter": {
"should": [
{
"key": "text",
"match": {
"value": true
},
"range": {
"lt": 1,
"gt": 1,
"gte": 1,
"lte": 1
},
"geo_bounding_box": {
"top_left": {
"lon": 1,
"lat": 1
},
"bottom_right": {
"lon": 1,
"lat": 1
}
},
"geo_radius": {
"center": {
"lon": 1,
"lat": 1
},
"radius": 1
},
"geo_polygon": {
"exterior": {
"points": [
{
"lon": 1,
"lat": 1
}
]
},
"interiors": [
{
"points": [
{
"lon": 1,
"lat": 1
}
]
}
]
},
"values_count": {
"lt": 1,
"gt": 1,
"gte": 1,
"lte": 1
},
"is_empty": true,
"is_null": true
}
],
"min_should": {
"conditions": "[Circular Reference]",
"min_count": 1
},
"must": [
{
"key": "text",
"match": {
"value": true
},
"range": {
"lt": 1,
"gt": 1,
"gte": 1,
"lte": 1
},
"geo_bounding_box": {
"top_left": {
"lon": 1,
"lat": 1
},
"bottom_right": {
"lon": 1,
"lat": 1
}
},
"geo_radius": {
"center": {
"lon": 1,
"lat": 1
},
"radius": 1
},
"geo_polygon": {
"exterior": {
"points": [
{
"lon": 1,
"lat": 1
}
]
},
"interiors": [
{
"points": [
{
"lon": 1,
"lat": 1
}
]
}
]
},
"values_count": {
"lt": 1,
"gt": 1,
"gte": 1,
"lte": 1
},
"is_empty": true,
"is_null": true
}
],
"must_not": [
{
"key": "text",
"match": {
"value": true
},
"range": {
"lt": 1,
"gt": 1,
"gte": 1,
"lte": 1
},
"geo_bounding_box": {
"top_left": {
"lon": 1,
"lat": 1
},
"bottom_right": {
"lon": 1,
"lat": 1
}
},
"geo_radius": {
"center": {
"lon": 1,
"lat": 1
},
"radius": 1
},
"geo_polygon": {
"exterior": {
"points": [
{
"lon": 1,
"lat": 1
}
]
},
"interiors": [
{
"points": [
{
"lon": 1,
"lat": 1
}
]
}
]
},
"values_count": {
"lt": 1,
"gt": 1,
"gte": 1,
"lte": 1
},
"is_empty": true,
"is_null": true
}
]
},
"offset": 1,
"limit": 1,
"temporal_relevance": 1,
"expand_query": true,
"interpret_filters": true,
"rerank": true,
"generate_answer": true
}{
"results": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"completion": "text"
}Last updated