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
/source-connections

List source connections with minimal fields for performance.

Authorizations
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
get
/source-connections
GET /source-connections HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "short_name": "text",
    "readable_collection_id": "text",
    "created_at": "2025-12-06T05:40:15.841Z",
    "modified_at": "2025-12-06T05:40:15.841Z",
    "is_authenticated": true,
    "entity_count": 0,
    "federated_search": false,
    "auth_method": "direct",
    "status": "active"
  }
]

Create

post
/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
x-api-keystringRequired

Organization API key for authentication

Header parameters
X-Organization-IDany ofOptional
stringOptional
or
nullOptional
Body

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
post
/source-connections
POST /source-connections HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 322

{
  "name": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "description": "text",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "continuous": false,
    "cursor_field": "text"
  },
  "sync_immediately": true,
  "authentication": {
    "credentials": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "redirect_url": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2025-12-06T05:40:15.841Z",
  "modified_at": "2025-12-06T05:40:15.841Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2025-12-06T05:40:15.841Z",
    "expires_at": "2025-12-06T05:40:15.841Z",
    "auth_url": "text",
    "auth_url_expires": "2025-12-06T05:40:15.841Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2025-12-06T05:40:15.841Z",
    "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": "2025-12-06T05:40:15.841Z",
      "completed_at": "2025-12-06T05:40:15.841Z",
      "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": "2025-12-06T05:40:15.841Z"
      }
    }
  },
  "federated_search": false
}

Get

get
/source-connections/{source_connection_id}

Get a source connection with optional depth expansion.

Authorizations
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
get
/source-connections/{source_connection_id}
GET /source-connections/{source_connection_id} HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2025-12-06T05:40:15.841Z",
  "modified_at": "2025-12-06T05:40:15.841Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2025-12-06T05:40:15.841Z",
    "expires_at": "2025-12-06T05:40:15.841Z",
    "auth_url": "text",
    "auth_url_expires": "2025-12-06T05:40:15.841Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2025-12-06T05:40:15.841Z",
    "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": "2025-12-06T05:40:15.841Z",
      "completed_at": "2025-12-06T05:40:15.841Z",
      "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": "2025-12-06T05:40:15.841Z"
      }
    }
  },
  "federated_search": false
}

Delete

delete
/source-connections/{source_connection_id}

Delete a source connection and all related data.

Authorizations
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
delete
/source-connections/{source_connection_id}
DELETE /source-connections/{source_connection_id} HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2025-12-06T05:40:15.841Z",
  "modified_at": "2025-12-06T05:40:15.841Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2025-12-06T05:40:15.841Z",
    "expires_at": "2025-12-06T05:40:15.841Z",
    "auth_url": "text",
    "auth_url_expires": "2025-12-06T05:40:15.841Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2025-12-06T05:40:15.841Z",
    "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": "2025-12-06T05:40:15.841Z",
      "completed_at": "2025-12-06T05:40:15.841Z",
      "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": "2025-12-06T05:40:15.841Z"
      }
    }
  },
  "federated_search": false
}

Update

patch
/source-connections/{source_connection_id}

Update a source connection.

Updateable fields:

  • name, description

  • config_fields

  • cron_schedule

  • auth_fields (direct auth only)

Authorizations
x-api-keystringRequired

Organization API key for authentication

Path parameters
source_connection_idstring · uuidRequired
Header parameters
X-Organization-IDany ofOptional
stringOptional
or
nullOptional
Body

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
patch
/source-connections/{source_connection_id}
PATCH /source-connections/{source_connection_id} HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "name": "text",
  "description": "text",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "continuous": false,
    "cursor_field": "text"
  },
  "authentication": {
    "credentials": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "short_name": "text",
  "readable_collection_id": "text",
  "status": "active",
  "created_at": "2025-12-06T05:40:15.841Z",
  "modified_at": "2025-12-06T05:40:15.841Z",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2025-12-06T05:40:15.841Z",
    "expires_at": "2025-12-06T05:40:15.841Z",
    "auth_url": "text",
    "auth_url_expires": "2025-12-06T05:40:15.841Z",
    "redirect_url": "text",
    "provider_readable_id": "text",
    "provider_id": "text"
  },
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "schedule": {
    "cron": "text",
    "next_run": "2025-12-06T05:40:15.841Z",
    "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": "2025-12-06T05:40:15.841Z",
      "completed_at": "2025-12-06T05:40:15.841Z",
      "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": "2025-12-06T05:40:15.841Z"
      }
    }
  },
  "federated_search": false
}

Run

post
/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
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
post
/source-connections/{source_connection_id}/run
POST /source-connections/{source_connection_id}/run HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "source_connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "started_at": "2025-12-06T05:40:15.841Z",
  "completed_at": "2025-12-06T05:40:15.841Z",
  "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
/source-connections/{source_connection_id}/jobs

Get sync jobs for a source connection.

Authorizations
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
get
/source-connections/{source_connection_id}/jobs
GET /source-connections/{source_connection_id}/jobs HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "source_connection_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "created",
    "started_at": "2025-12-06T05:40:15.841Z",
    "completed_at": "2025-12-06T05:40:15.841Z",
    "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
/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
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
post
/source-connections/{source_connection_id}/jobs/{job_id}/cancel
POST /source-connections/{source_connection_id}/jobs/{job_id}/cancel HTTP/1.1
Host: api.graffo.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "source_connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "started_at": "2025-12-06T05:40:15.841Z",
  "completed_at": "2025-12-06T05:40:15.841Z",
  "duration_seconds": 1,
  "entities_inserted": 0,
  "entities_updated": 0,
  "entities_deleted": 0,
  "entities_failed": 0,
  "error": "text",
  "error_details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
PreviousCollectionsNextSources

Last updated