Sources

API endpoints for discovering available data source connectors and their configuration requirements

List

get

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

/sources

List all available data source connectors.

Returns the complete catalog of source types that Graffo can connect to.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Complete source representation with authentication and configuration schemas.

namestringRequired

Human-readable name of the data source connector (e.g., 'GitHub', 'Stripe', 'PostgreSQL').

descriptionany ofOptional

Detailed description explaining what data this source can extract and its typical use cases.

stringOptional

or

nullOptional

auth_methodsany ofOptional

List of supported authentication methods (e.g., 'direct', 'oauth_browser').

string[]Optional

or

nullOptional

oauth_typeany ofOptional

OAuth token type for OAuth sources (e.g., 'access_only', 'with_refresh').

stringOptional

or

nullOptional

requires_byocbooleanOptional

Whether this OAuth source requires users to bring their own client.

Default: false

auth_config_classany ofOptional

Python class name that defines the authentication configuration fields required for this source (only for DIRECT auth).

stringOptional

or

nullOptional

config_classany ofOptional

Python class name that defines the source-specific configuration options and parameters.

stringOptional

or

nullOptional

short_namestringRequired

Technical identifier used internally to reference this source type. Must be unique across all sources.

class_namestringRequired

Python class name of the source implementation that handles data extraction logic.

output_entity_definition_idsany ofOptional

List of entity definition IDs that this source can produce. Defines the data schema and structure that this connector outputs.

string[]Optional

or

nullOptional

labelsany ofOptional

Categorization tags to help users discover and filter sources by domain or use case.

string[]Optional

or

nullOptional

supports_continuousbooleanOptional

Whether this source supports cursor-based continuous syncing for incremental data extraction. Sources with this capability can track their sync position and resume from where they left off.

Default: false

federated_searchbooleanOptional

Whether this source uses federated search instead of traditional syncing. Federated search sources query data in real-time during searches rather than syncing and indexing all data beforehand.

Default: false

supports_temporal_relevancebooleanOptional

Whether this source's entities have timestamps that enable recency-based ranking. Sources without file-level timestamps (e.g., code repositories) cannot use temporal relevance for search result weighting.

Default: true

rate_limit_levelany ofOptional

Rate limiting level for this source: 'org' (organization-wide), 'connection' (per-connection/per-user), or None (no rate limiting).

stringOptional

or

nullOptional

idstring · uuidRequired

Unique system identifier for this source type. Generated automatically when the source is registered.

created_atstring · date-timeRequired

Timestamp when this source type was registered in the system (ISO 8601 format).

modified_atstring · date-timeRequired

Timestamp when this source type was last updated (ISO 8601 format).

auth_fieldsany ofOptional

Schema definition for authentication fields required to connect to this source. Only present for sources using DIRECT authentication. OAuth sources handle authentication through browser flows.

or

nullOptional

supported_auth_providersany ofOptional

List of auth provider short names that support this source (e.g., ['composio', 'pipedream']). Computed dynamically for API responses. This field is not stored in the database.

string[]Optional

or

nullOptional

422

Validation Error

application/json

get

/sources

Python SDKTypeScript SDK

from graffo import GraffoSDK

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

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "GitHub",
    "description": "Connect to GitHub repositories for code, issues, pull requests, and documentation",
    "auth_type": "config_class",
    "auth_config_class": "GitHubAuthConfig",
    "config_class": "GitHubConfig",
    "short_name": "github",
    "class_name": "GitHubSource",
    "output_entity_definition_ids": [
      "def12345-6789-abcd-ef01-234567890abc",
      "def67890-abcd-ef01-2345-67890abcdef1"
    ],
    "labels": [
      "code"
    ],
    "created_at": "2024-01-01T00:00:00Z",
    "modified_at": "2024-01-01T00:00:00Z",
    "auth_fields": {
      "fields": [
        {
          "name": "personal_access_token",
          "title": "Personal Access Token",
          "description": "GitHub Personal Access Token with repository read permissions",
          "type": "string",
          "secret": true
        },
        {
          "name": "repo_name",
          "title": "Repository Name",
          "description": "Full repository name in format 'owner/repo'",
          "type": "string"
        }
      ]
    }
  }
]

Get

get

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

/sources/{short_name}

Get detailed information about a specific data source connector.

Authorizations

ApiKeyAuthAgentKeyAuth

x-api-keystringRequired

Organization API key for authentication

Path parameters

short_namestringRequired

Technical identifier of the source type (e.g., 'github', 'stripe', 'slack')

Header parameters

X-Organization-IDany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Complete source representation with authentication and configuration schemas.

namestringRequired

Human-readable name of the data source connector (e.g., 'GitHub', 'Stripe', 'PostgreSQL').

descriptionany ofOptional

Detailed description explaining what data this source can extract and its typical use cases.

stringOptional

or

nullOptional

auth_methodsany ofOptional

List of supported authentication methods (e.g., 'direct', 'oauth_browser').

string[]Optional

or

nullOptional

oauth_typeany ofOptional

OAuth token type for OAuth sources (e.g., 'access_only', 'with_refresh').

stringOptional

or

nullOptional

requires_byocbooleanOptional

Whether this OAuth source requires users to bring their own client.

Default: false

auth_config_classany ofOptional

Python class name that defines the authentication configuration fields required for this source (only for DIRECT auth).

stringOptional

or

nullOptional

config_classany ofOptional

Python class name that defines the source-specific configuration options and parameters.

stringOptional

or

nullOptional

short_namestringRequired

Technical identifier used internally to reference this source type. Must be unique across all sources.

class_namestringRequired

Python class name of the source implementation that handles data extraction logic.

output_entity_definition_idsany ofOptional

List of entity definition IDs that this source can produce. Defines the data schema and structure that this connector outputs.

string[]Optional

or

nullOptional

labelsany ofOptional

Categorization tags to help users discover and filter sources by domain or use case.

string[]Optional

or

nullOptional

supports_continuousbooleanOptional

Whether this source supports cursor-based continuous syncing for incremental data extraction. Sources with this capability can track their sync position and resume from where they left off.

Default: false

federated_searchbooleanOptional

Whether this source uses federated search instead of traditional syncing. Federated search sources query data in real-time during searches rather than syncing and indexing all data beforehand.

Default: false

supports_temporal_relevancebooleanOptional

Whether this source's entities have timestamps that enable recency-based ranking. Sources without file-level timestamps (e.g., code repositories) cannot use temporal relevance for search result weighting.

Default: true

rate_limit_levelany ofOptional

Rate limiting level for this source: 'org' (organization-wide), 'connection' (per-connection/per-user), or None (no rate limiting).

stringOptional

or

nullOptional

idstring · uuidRequired

Unique system identifier for this source type. Generated automatically when the source is registered.

created_atstring · date-timeRequired

Timestamp when this source type was registered in the system (ISO 8601 format).

modified_atstring · date-timeRequired

Timestamp when this source type was last updated (ISO 8601 format).

auth_fieldsany ofOptional

Schema definition for authentication fields required to connect to this source. Only present for sources using DIRECT authentication. OAuth sources handle authentication through browser flows.

or

nullOptional

supported_auth_providersany ofOptional

List of auth provider short names that support this source (e.g., ['composio', 'pipedream']). Computed dynamically for API responses. This field is not stored in the database.

string[]Optional

or

nullOptional

422

Validation Error

application/json

get

/sources/{short_name}

Python SDKTypeScript SDK

from graffo import GraffoSDK

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

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "GitHub",
  "description": "Connect to GitHub repositories for code, issues, pull requests, and documentation",
  "auth_type": "config_class",
  "auth_config_class": "GitHubAuthConfig",
  "config_class": "GitHubConfig",
  "short_name": "github",
  "class_name": "GitHubSource",
  "output_entity_definition_ids": [
    "def12345-6789-abcd-ef01-234567890abc",
    "def67890-abcd-ef01-2345-67890abcdef1"
  ],
  "labels": [
    "code"
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "modified_at": "2024-01-01T00:00:00Z",
  "auth_fields": {
    "fields": [
      {
        "name": "personal_access_token",
        "title": "Personal Access Token",
        "description": "GitHub Personal Access Token with repository read permissions",
        "type": "string",
        "secret": true
      },
      {
        "name": "repo_name",
        "title": "Repository Name",
        "description": "Full repository name in format 'owner/repo'",
        "type": "string"
      }
    ]
  }
}