> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seynlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom source

> Register a source for any system Seyn has no prebuilt connector for.

Step one of bringing your own data. Register a custom source and you get back a `sourceId` to push records to via [Ingest records](/api-reference/ingest-records).

The optional `entityTypes` hint lists the kinds of records you'll send (`deal`, `ticket`, `task`). It improves how Seyn routes normalization, but you can ingest entity types you didn't declare.

Requires an API key with the `ingest` scope.


## OpenAPI

````yaml openapi.yaml POST /v1/sources
openapi: 3.1.0
info:
  title: Seyn API
  version: 1.0.0
  description: >
    Programmatic access to Seyn for your organization.


    - **Ingest** data from any source with the Ingestion endpoints (requires a
    key with the `ingest` scope).

    - **Read** extracted process knowledge: search, rules, libraries,
    provenance, and metrics.


    Authenticate with a bearer API key (`sk_live_*`); each key is scoped to a
    single organization.
  contact:
    name: Seyn Support
    email: support@seynlabs.com
    url: https://seynlabs.com
servers:
  - url: https://api.seynlabs.com
    description: Production
  - url: https://api-dev.seynlabs.com
    description: Staging
security:
  - bearerAuth: []
tags:
  - name: Ingestion
    description: >-
      Push data into Seyn from any source: register a custom source and stream
      records to it
  - name: Knowledge
    description: Natural-language search over extracted knowledge
  - name: Rules
    description: Process rules, the atomic knowledge units extracted by the pipeline
  - name: Libraries
    description: Versioned snapshots of extracted knowledge for your organization
  - name: Patterns
    description: Aggregate pipeline analytics
paths:
  /v1/sources:
    post:
      tags:
        - Ingestion
      summary: Create a custom source
      description: >
        Register a custom source to ingest data from any system Seyn has no
        prebuilt

        connector for. Returns a `sourceId` you then push records to via `POST
        /v1/ingest`.


        Requires an API key with the `ingest` scope.
      operationId: sourcesCreate
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Optional. Reuse the same key when retrying so a source is created
            only once.
          example: f0e1d2c3-b4a5-4968-8778-695a4b3c2d1e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourceRequest'
            examples:
              crm:
                summary: A custom CRM
                value:
                  name: Internal CRM
                  entityTypes:
                    - deal
                    - account
                    - activity
                  description: Deals and activity from our in-house CRM
      responses:
        '201':
          description: Source created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope_Source'
              example:
                success: true
                data:
                  id: b6f1c0de-1f2a-4c3b-9d4e-5a6b7c8d9e0f
                  type: custom_api
                  name: Internal CRM
                  status: active
                  createdAt: '2026-06-12T16:20:00Z'
                meta:
                  requestId: f0e1d2c3-b4a5-4968-8778-695a4b3c2d1e
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CreateSourceRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Human-readable name shown in the dashboard.
        entityTypes:
          type: array
          items:
            type: string
          description: >-
            Optional hint listing the entity types you'll send. Improves
            normalization routing.
        description:
          type: string
      required:
        - name
    SuccessEnvelope_Source:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          $ref: '#/components/schemas/Source'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - success
        - data
        - meta
    Source:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          description: >-
            Connector type. `custom_api` for sources you create; otherwise the
            prebuilt connector type (for example `sharepoint`, `teams`).
          example: custom_api
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - paused
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - type
        - name
        - status
        - createdAt
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Per-request UUID; quote in support tickets.
      additionalProperties: true
      required:
        - requestId
    ErrorBody:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - MISSING_AUTH_HEADER
                - INVALID_API_KEY
                - KEY_REVOKED
                - RATE_LIMITED
                - NOT_FOUND
                - LIBRARY_NOT_FOUND
                - SOURCE_NOT_FOUND
                - VALIDATION_ERROR
                - INSUFFICIENT_SCOPE
                - PAYLOAD_TOO_LARGE
                - INTERNAL_ERROR
            message:
              type: string
          required:
            - code
            - message
      required:
        - success
        - error
  responses:
    ValidationError:
      description: Request parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            validationError:
              value:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Query parameter 'q' is required
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            missing:
              summary: No Authorization header
              value:
                success: false
                error:
                  code: MISSING_AUTH_HEADER
                  message: 'Authorization: Bearer <api-key> header is required'
            invalid:
              summary: Unrecognized key
              value:
                success: false
                error:
                  code: INVALID_API_KEY
                  message: API key is invalid or unrecognized
    InsufficientScope:
      description: The API key is read-only; write operations need the `ingest` scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            insufficientScope:
              value:
                success: false
                error:
                  code: INSUFFICIENT_SCOPE
                  message: This API key is read-only; an ingest-scoped key is required
    RateLimited:
      description: Per-key rate limit exceeded (default 60 req/min/key).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            rateLimited:
              value:
                success: false
                error:
                  code: RATE_LIMITED
                  message: Rate limit exceeded for this API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_live_*
      description: |
        Bearer token from `app.seynlabs.com` → Settings → API Keys.
        Send as `Authorization: Bearer sk_live_...`.

````