> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.adapter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a custom connector
> Create a new custom connector. The response includes the `connector_id`
you'll use in the `/v1/custom-connectors/{connector_id}/ingest…` paths.
## OpenAPI
````yaml POST /v1/custom-connectors
openapi: 3.1.0
info:
title: Adapter API
description: Connect and sync data from any SaaS tool.
version: 0.1.0
servers:
- url: https://api.adapter.com
security:
- ApiKeyAuth: []
tags:
- name: connections
description: Manage OAuth connections to data sources.
paths:
/v1/custom-connectors:
post:
tags:
- custom-connectors
summary: Create a custom connector
description: |-
Create a new custom connector. The response includes the `connector_id`
you'll use in the `/v1/custom-connectors/{connector_id}/ingest…` paths.
operationId: create_custom_connector
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateClientRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomConnectorCreateResponse'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationErrorModel'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionDeniedErrorModel'
description: Forbidden
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorModel'
description: Internal Server Error
components:
schemas:
CreateClientRequest:
properties:
name:
type: string
title: Name
source_name:
type: string
title: Source Name
accepted_kinds:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Accepted Kinds
description: >-
First-party event kinds this connector may emit. Empty/None = all
kinds allowed.
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
description: >-
Key/value metadata applied to every event from this connector.
String values only.
examples:
- env: staging
pipeline: acme-crm@v2
type: object
required:
- name
- source_name
title: CreateClientRequest
CustomConnectorCreateResponse:
properties:
connector_id:
type: string
title: Connector Id
description: Unique identifier for the connector.
examples:
- c0ffee01-1234-5678-90ab-cdef01234567
name:
type: string
title: Name
description: Human display name.
examples:
- Acme CRM
source_name:
type: string
title: Source Name
description: Immutable slug used in the event source (`custom:`).
examples:
- acme-crm
accepted_kinds:
items:
type: string
type: array
title: Accepted Kinds
description: >-
First-party event kinds this connector may emit. Empty = all kinds
allowed.
examples:
- - email
- page
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
description: >-
Key/value metadata applied to every event from this connector.
String values only. Per-item `metadata` on ingest overrides on key
conflict.
examples:
- env: staging
created_at:
type: string
title: Created At
description: ISO 8601 creation timestamp.
created_by:
$ref: '#/components/schemas/CreatedBy'
is_active:
type: boolean
title: Is Active
description: False once the connector has been deactivated.
type: object
required:
- connector_id
- name
- source_name
- created_at
- created_by
- is_active
title: CustomConnectorCreateResponse
description: |-
Returned on creation. Auth for ingest is via platform API keys
(`pk_live_…`); call `/v1/custom-connectors/{connector_id}/ingest…` with
`Authorization: Bearer pk_live_…` to push data.
AuthenticationErrorModel:
properties:
error_code:
type: string
const: authentication_error
title: Error Code
default: authentication_error
message:
type: string
title: Message
default: Invalid or missing credentials.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: AuthenticationErrorModel
PermissionDeniedErrorModel:
properties:
error_code:
type: string
const: permission_denied
title: Error Code
default: permission_denied
message:
type: string
title: Message
default: You do not have permission to perform this action.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: PermissionDeniedErrorModel
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
InternalServerErrorModel:
properties:
error_code:
type: string
const: internal_server_error
title: Error Code
default: internal_server_error
message:
type: string
title: Message
default: An unexpected error occurred.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: InternalServerErrorModel
CreatedBy:
properties:
type:
type: string
enum:
- user
- api_key
title: Type
description: Principal type that created the resource.
examples:
- user
id:
type: string
title: Id
description: user_id for user callers, key_id for API key callers.
examples:
- u_01abc123
type: object
required:
- type
- id
title: CreatedBy
description: |-
Principal that created a resource. `id` is a user_id for `type="user"`
and a key_id (UUID) for `type="api_key"`.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: Pass your `pk_live_...` API key as a Bearer token.
````