Source Connections

API endpoints for managing live connections to data sources. Source connections are the configured instances Graffo uses to sync data from your apps and databases into collections

List

get

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

/source-connections

List source connections with minimal fields for performance.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Query parameters

collectionany ofOptional

Filter by collection readable ID

stringOptional

or

nullOptional

skipintegerOptionalDefault: 0

limitinteger · min: 1 · max: 1000OptionalDefault: 100

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Clean source connection for list views.

idstring · uuidRequired

namestringRequired

short_namestringRequired

readable_collection_idstringRequired

created_atstring · date-timeRequired

modified_atstring · date-timeRequired

is_authenticatedbooleanRequired

entity_countintegerOptionalDefault: 0

federated_searchbooleanOptional

Whether this source uses federated search

Default: false

auth_methodstring · enumRead-onlyRequired

Get authentication method from database value.

Possible values:

statusstring · enumRead-onlyRequired

Compute connection status from current state.

Possible values:

422

Validation Error

application/json

get

/source-connections

Python SDKTypeScript SDK

from graffo import GraffoSDK

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

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "short_name": "text",
    "readable_collection_id": "text",
    "created_at": "2026-04-02T02:17:34.781Z",
    "modified_at": "2026-04-02T02:17:34.781Z",
    "is_authenticated": true,
    "entity_count": 0,
    "federated_search": false,
    "auth_method": "direct",
    "status": "active"
  }
]

Create

post

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

/source-connections

Create a new source connection.

The authentication configuration determines the flow:

• DirectAuthentication: Immediate creation with provided credentials

• OAuthBrowserAuthentication: Returns shell with authentication URL

• OAuthTokenAuthentication: Immediate creation with provided token

• AuthProviderAuthentication: Using external auth provider

BYOC (Bring Your Own Client) is detected when client_id and client_secret are provided in OAuthBrowserAuthentication.

sync_immediately defaults:

• True for: direct, oauth_token, auth_provider

• False for: oauth_browser, oauth_byoc (these sync after authentication)

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Body

application/json

Create source connection with nested authentication.

nameany ofOptional

Connection name (defaults to '{Source Name} Connection')

string · min: 4 · max: 42Optional

or

nullOptional

short_namestringRequired

Source identifier (e.g., 'slack', 'github')

readable_collection_idstringRequired

Collection readable ID

descriptionany ofOptional

Connection description

string · max: 255Optional

or

nullOptional

configany ofOptional

Source-specific configuration

or

nullOptional

scheduleany ofOptional

or

nullOptional

sync_immediatelyany ofOptional

Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)

booleanOptional

or

nullOptional

authenticationany ofOptional

Authentication config (defaults to OAuth browser flow for OAuth sources)

or

or

or

or

nullOptional

redirect_urlany ofOptional

URL to redirect to after OAuth flow completes (only used for OAuth flows)

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Complete source connection details.

idstring · uuidRequired

namestringRequired

descriptionany ofRequired

stringOptional

or

nullOptional

short_namestringRequired

readable_collection_idstringRequired

statusstring · enumRequired

Source connection status enum - represents overall connection state.

Possible values:

created_atstring · date-timeRequired

modified_atstring · date-timeRequired

configany ofOptional

or

nullOptional

scheduleany ofOptional

or

nullOptional

syncany ofOptional

or

nullOptional

sync_idany ofOptional

ID of the associated sync

string · uuidOptional

or

nullOptional

entitiesany ofOptional

or

nullOptional

federated_searchbooleanOptional

Whether this source uses federated search

Default: false

422

Validation Error

application/json

post

/source-connections

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.source_connections.create(
    source_id="source_id",
    readable_id="my-connection",
    config={},
)
print(resp)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2026-04-02T02:17:34.781Z",
  "modified_at": "2026-04-02T02:17:34.781Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2026-04-02T02:17:34.781Z",
    "expires_at": "2026-04-02T02:17:34.781Z",
    "auth_url": "text",
    "auth_url_expires": "2026-04-02T02:17:34.781Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2026-04-02T02:17:34.781Z",
    "continuous": false,
    "cursor_field": "text",
    "cursor_value": null
  },
  "sync": {
    "total_runs": 0,
    "successful_runs": 0,
    "failed_runs": 0,
    "last_job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "created",
      "started_at": "2026-04-02T02:17:34.781Z",
      "completed_at": "2026-04-02T02:17:34.781Z",
      "duration_seconds": 1,
      "entities_inserted": 0,
      "entities_updated": 0,
      "entities_deleted": 0,
      "entities_failed": 0,
      "error": "text"
    }
  },
  "sync_id": "123e4567-e89b-12d3-a456-426614174000",
  "entities": {
    "total_entities": 0,
    "by_type": {
      "ANY_ADDITIONAL_PROPERTY": {
        "count": 1,
        "last_updated": "2026-04-02T02:17:34.781Z"
      }
    }
  },
  "federated_search": false
}

Get

get

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

/source-connections/{source_connection_id}

Get a source connection with optional depth expansion.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

source_connection_idstring · uuidRequired

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Complete source connection details.

idstring · uuidRequired

namestringRequired

descriptionany ofRequired

stringOptional

or

nullOptional

short_namestringRequired

readable_collection_idstringRequired

statusstring · enumRequired

Source connection status enum - represents overall connection state.

Possible values:

created_atstring · date-timeRequired

modified_atstring · date-timeRequired

configany ofOptional

or

nullOptional

scheduleany ofOptional

or

nullOptional

syncany ofOptional

or

nullOptional

sync_idany ofOptional

ID of the associated sync

string · uuidOptional

or

nullOptional

entitiesany ofOptional

or

nullOptional

federated_searchbooleanOptional

Whether this source uses federated search

Default: false

422

Validation Error

application/json

get

/source-connections/{source_connection_id}

Python SDKTypeScript SDK

from graffo import GraffoSDK

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2026-04-02T02:17:34.781Z",
  "modified_at": "2026-04-02T02:17:34.781Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2026-04-02T02:17:34.781Z",
    "expires_at": "2026-04-02T02:17:34.781Z",
    "auth_url": "text",
    "auth_url_expires": "2026-04-02T02:17:34.781Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2026-04-02T02:17:34.781Z",
    "continuous": false,
    "cursor_field": "text",
    "cursor_value": null
  },
  "sync": {
    "total_runs": 0,
    "successful_runs": 0,
    "failed_runs": 0,
    "last_job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "created",
      "started_at": "2026-04-02T02:17:34.781Z",
      "completed_at": "2026-04-02T02:17:34.781Z",
      "duration_seconds": 1,
      "entities_inserted": 0,
      "entities_updated": 0,
      "entities_deleted": 0,
      "entities_failed": 0,
      "error": "text"
    }
  },
  "sync_id": "123e4567-e89b-12d3-a456-426614174000",
  "entities": {
    "total_entities": 0,
    "by_type": {
      "ANY_ADDITIONAL_PROPERTY": {
        "count": 1,
        "last_updated": "2026-04-02T02:17:34.781Z"
      }
    }
  },
  "federated_search": false
}

Delete

delete

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

/source-connections/{source_connection_id}

Delete a source connection and all related data.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

source_connection_idstring · uuidRequired

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Complete source connection details.

idstring · uuidRequired

namestringRequired

descriptionany ofRequired

stringOptional

or

nullOptional

short_namestringRequired

readable_collection_idstringRequired

statusstring · enumRequired

Source connection status enum - represents overall connection state.

Possible values:

created_atstring · date-timeRequired

modified_atstring · date-timeRequired

configany ofOptional

or

nullOptional

scheduleany ofOptional

or

nullOptional

syncany ofOptional

or

nullOptional

sync_idany ofOptional

ID of the associated sync

string · uuidOptional

or

nullOptional

entitiesany ofOptional

or

nullOptional

federated_searchbooleanOptional

Whether this source uses federated search

Default: false

422

Validation Error

application/json

delete

/source-connections/{source_connection_id}

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.source_connections.delete(source_connection_id="source_connection_id")
print(resp)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2026-04-02T02:17:34.781Z",
  "modified_at": "2026-04-02T02:17:34.781Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2026-04-02T02:17:34.781Z",
    "expires_at": "2026-04-02T02:17:34.781Z",
    "auth_url": "text",
    "auth_url_expires": "2026-04-02T02:17:34.781Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2026-04-02T02:17:34.781Z",
    "continuous": false,
    "cursor_field": "text",
    "cursor_value": null
  },
  "sync": {
    "total_runs": 0,
    "successful_runs": 0,
    "failed_runs": 0,
    "last_job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "created",
      "started_at": "2026-04-02T02:17:34.781Z",
      "completed_at": "2026-04-02T02:17:34.781Z",
      "duration_seconds": 1,
      "entities_inserted": 0,
      "entities_updated": 0,
      "entities_deleted": 0,
      "entities_failed": 0,
      "error": "text"
    }
  },
  "sync_id": "123e4567-e89b-12d3-a456-426614174000",
  "entities": {
    "total_entities": 0,
    "by_type": {
      "ANY_ADDITIONAL_PROPERTY": {
        "count": 1,
        "last_updated": "2026-04-02T02:17:34.781Z"
      }
    }
  },
  "federated_search": false
}

Update

patch

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

/source-connections/{source_connection_id}

Update a source connection.

Updateable fields:

• name, description

• config_fields

• cron_schedule

• auth_fields (direct auth only)

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

source_connection_idstring · uuidRequired

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Body

application/json

Update schema for source connections.

nameany ofOptional

string · min: 4 · max: 42Optional

or

nullOptional

descriptionany ofOptional

string · max: 255Optional

or

nullOptional

configany ofOptional

Source-specific configuration

or

nullOptional

scheduleany ofOptional

or

nullOptional

authenticationany ofOptional

Authentication config (defaults to OAuth browser flow for OAuth sources)

or

or

or

or

nullOptional

Responses

200

Successful Response

application/json

Complete source connection details.

idstring · uuidRequired

namestringRequired

descriptionany ofRequired

stringOptional

or

nullOptional

short_namestringRequired

readable_collection_idstringRequired

statusstring · enumRequired

Source connection status enum - represents overall connection state.

Possible values:

created_atstring · date-timeRequired

modified_atstring · date-timeRequired

configany ofOptional

or

nullOptional

scheduleany ofOptional

or

nullOptional

syncany ofOptional

or

nullOptional

sync_idany ofOptional

ID of the associated sync

string · uuidOptional

or

nullOptional

entitiesany ofOptional

or

nullOptional

federated_searchbooleanOptional

Whether this source uses federated search

Default: false

422

Validation Error

application/json

patch

/source-connections/{source_connection_id}

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.source_connections.update(
    source_connection_id="source_connection_id",
    config={},
)
print(resp)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2026-04-02T02:17:34.781Z",
  "modified_at": "2026-04-02T02:17:34.781Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2026-04-02T02:17:34.781Z",
    "expires_at": "2026-04-02T02:17:34.781Z",
    "auth_url": "text",
    "auth_url_expires": "2026-04-02T02:17:34.781Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2026-04-02T02:17:34.781Z",
    "continuous": false,
    "cursor_field": "text",
    "cursor_value": null
  },
  "sync": {
    "total_runs": 0,
    "successful_runs": 0,
    "failed_runs": 0,
    "last_job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "created",
      "started_at": "2026-04-02T02:17:34.781Z",
      "completed_at": "2026-04-02T02:17:34.781Z",
      "duration_seconds": 1,
      "entities_inserted": 0,
      "entities_updated": 0,
      "entities_deleted": 0,
      "entities_failed": 0,
      "error": "text"
    }
  },
  "sync_id": "123e4567-e89b-12d3-a456-426614174000",
  "entities": {
    "total_entities": 0,
    "by_type": {
      "ANY_ADDITIONAL_PROPERTY": {
        "count": 1,
        "last_updated": "2026-04-02T02:17:34.781Z"
      }
    }
  },
  "federated_search": false
}

Run

post

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

/source-connections/{source_connection_id}/run

Trigger a sync run for a source connection.

Runs are always executed through Temporal workflow engine.

Args: db: Database session source_connection_id: ID of the source connection to run ctx: API context with organization and user information guard_rail: Guard rail service for usage limits force_full_sync: If True, forces a full sync with orphaned entity cleanup for continuous syncs. Raises 400 error if used on non-continuous syncs (which are always full syncs).

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

source_connection_idstring · uuidRequired

Query parameters

force_full_syncbooleanOptional

Force a full sync ignoring cursor data instead of waiting for the daily cleanup schedule. Only allowed for continuous syncs.

Default: false

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

/source-connections/{source_connection_id}/run

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.source_connections.run(source_connection_id="source_connection_id")
print(resp)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "source_connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "started_at": "2026-04-02T02:17:34.781Z",
  "completed_at": "2026-04-02T02:17:34.781Z",
  "duration_seconds": 1,
  "entities_inserted": 0,
  "entities_updated": 0,
  "entities_deleted": 0,
  "entities_failed": 0,
  "error": "text",
  "error_details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Source Connection Jobs

get

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

/source-connections/{source_connection_id}/jobs

Get sync jobs for a source connection.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

source_connection_idstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 1000OptionalDefault: 100

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

get

/source-connections/{source_connection_id}/jobs

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.source_connections.get_jobs(source_connection_id="source_connection_id")
print(resp)

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "source_connection_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "created",
    "started_at": "2026-04-02T02:17:34.781Z",
    "completed_at": "2026-04-02T02:17:34.781Z",
    "duration_seconds": 1,
    "entities_inserted": 0,
    "entities_updated": 0,
    "entities_deleted": 0,
    "entities_failed": 0,
    "error": "text",
    "error_details": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Cancel Job

post

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

/source-connections/{source_connection_id}/jobs/{job_id}/cancel

Cancel a running sync job for a source connection.

This endpoint requests cancellation and marks the job as CANCELLING. The workflow updates the final status to CANCELLED when it processes the cancellation request.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

source_connection_idstring · uuidRequired

job_idstring · uuidRequired

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

/source-connections/{source_connection_id}/jobs/{job_id}/cancel

Python SDKTypeScript SDK

from graffo import GraffoSDK

client = GraffoSDK(base_url="https://api.graffo.io", api_key="YOUR_API_KEY")
resp = client.source_connections.cancel_job(
    source_connection_id="source_connection_id",
    job_id="job_id",
)
print(resp)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "source_connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "started_at": "2026-04-02T02:17:34.781Z",
  "completed_at": "2026-04-02T02:17:34.781Z",
  "duration_seconds": 1,
  "entities_inserted": 0,
  "entities_updated": 0,
  "entities_deleted": 0,
  "entities_failed": 0,
  "error": "text",
  "error_details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}