> ## Documentation Index > Fetch the complete documentation index at: https://docs.deck.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a source > Registers a new source. A source is a website or service that your agents connect to. ## OpenAPI ````yaml /api-reference/v2.json post /sources openapi: 3.1.1 info: title: Deck API version: 2.0.0 servers: - url: https://api.deck.co/v2 description: Production security: - BearerAuth: [] tags: - name: Agents description: >- Agents are the AI workers that execute tasks against sources. Create and manage the agents in your organization. - name: Components description: >- Embeddable UI components. Create short-lived session tokens for the Auth Component. - name: Platform description: Organization-wide platform settings, such as the static IP range. - name: Credentials description: >- Credentials store the login details an agent uses at a source. Values are tokenized at rest and never returned in plaintext. - name: Event Destinations description: >- Where Deck delivers events: webhooks, SQS, Kinesis, S3, and more. Manage destinations and inspect delivery attempts. - name: Events description: >- Immutable records of things that happened in your organization, such as a task run completing or a credential being verified. - name: Sessions description: >- Sessions are agent sandbox lifetimes. A session is created for each task run (or explicitly) and counts toward your concurrency limit. - name: Sources description: >- Sources are the websites and portals agents work against. Register, inspect, reset, and delete them. - name: Storage description: >- Files produced by task runs: downloaded documents, exports, and extraction results. - name: Task Runs description: >- A task run is one execution of a task. Inspect status and output, retrieve files and screenshots, cancel runs, and answer interaction requests. - name: Tasks description: >- Tasks define reusable units of work for an agent: a goal, an input schema, and an output schema. Run them against sources with credentials. - name: Test description: Connectivity check for your API key. - name: Triggers description: Triggers run tasks automatically on a schedule or in response to events. - name: Workflows - name: Workflow Runs paths: /sources: post: tags: - Sources summary: Create a source description: >- Registers a new source. A source is a website or service that your agents connect to. operationId: createSource parameters: - name: Idempotency-Key in: header required: false description: >- Optional key that makes the request idempotent. Retrying with the same key returns the original response instead of repeating the operation; keys expire after 24 hours. Any string up to 256 characters. See [Idempotency](/api/idempotency). schema: type: string maxLength: 256 example: 550e8400-e29b-41d4-a716-446655440000 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSourceRequest' text/json: schema: $ref: '#/components/schemas/CreateSourceRequest' application/*+json: schema: $ref: '#/components/schemas/CreateSourceRequest' required: true responses: '200': description: >- An existing source with the same URL was returned. Sources are deduplicated by their normalized URL, so creating a source that already exists returns the existing source with `200` instead of `201`. content: text/plain: schema: $ref: '#/components/schemas/CreateSourceResponse' application/json: schema: $ref: '#/components/schemas/CreateSourceResponse' text/json: schema: $ref: '#/components/schemas/CreateSourceResponse' '201': description: The source was created. content: text/plain: schema: $ref: '#/components/schemas/CreateSourceResponse' application/json: schema: $ref: '#/components/schemas/CreateSourceResponse' text/json: schema: $ref: '#/components/schemas/CreateSourceResponse' '400': description: Bad request — validation error or malformed input. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized. '403': description: Forbidden. '404': description: Not found — the requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Conflict — the request is valid but cannot be completed in the current state. Also returned when an `Idempotency-Key` is reused with different request parameters (`idempotency_error`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Unprocessable content — the request body is understood but contains invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Too many requests — the organization-wide API rate limit was exceeded (`rate_limit_exceeded`). Retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreateSourceRequest: required: - type - website type: object properties: type: type: string description: >- The source type. `website` is currently the only supported type; it defaults to `website` if omitted. website: $ref: '#/components/schemas/SourceWebsite' description: Website configuration for the source. name: type: - 'null' - string description: Display name for the source. headers: oneOf: - type: 'null' - $ref: '#/components/schemas/SourceHeadersRequest' description: >- Optional [custom headers](/platform/source-headers) Deck attaches to every request to the source's host, such as an access gateway's service token. Available on Enterprise plans as an add-on; returns `feature_not_available` until enabled for your organization. network: $ref: '#/components/schemas/SourceNetworkRequest' description: >- Optional [network](/platform/static-ips) for the source. Set `{ "type": "static_ips" }` to run every run against the source from Deck's static IP range. Omit for Deck's default IPs. Available on Enterprise plans as an add-on; returns `feature_not_available` until enabled for your organization. description: Request body for creating a new source. CreateSourceResponse: required: - id - object - name - type - website - created_at - updated_at - request_id - network type: object properties: id: type: string description: Unique identifier for the source, prefixed with `src_`. pattern: ^src_ example: src_AbC123xYz456 object: type: string description: Always `source`. name: type: - 'null' - string description: Display name for the source. type: type: string description: >- The source type. `website` is currently the only supported type; it defaults to `website` if omitted. website: $ref: '#/components/schemas/SourceWebsite' description: Website configuration for the source. network: $ref: '#/components/schemas/SourceNetworkResponse' description: The source's [network](/platform/static-ips). Always present. created_at: type: string format: date-time description: ISO 8601 timestamp of when the resource was created. example: '2026-08-24T12:00:00Z' updated_at: type: string format: date-time description: ISO 8601 timestamp of when the resource was last updated. example: '2026-08-24T12:00:00Z' request_id: type: string description: >- Unique identifier for the API request. Include this when contacting support. headers: oneOf: - type: 'null' - $ref: '#/components/schemas/SourceHeadersResponse' description: Request headers configured on the source. Omitted when none are set. description: >- A source object. Sources are websites or services that agents connect to. ValidationErrorResponse: required: - errors type: object properties: type: type: - 'null' - string description: RFC 9110 problem type URI. title: type: - 'null' - string description: Short summary of the validation failure. status: type: - 'null' - integer description: HTTP status code. format: int32 errors: type: object additionalProperties: type: array items: type: string description: Validation errors grouped by field name. traceId: type: - 'null' - string description: Request trace identifier. description: Validation error returned for malformed requests (HTTP 400). ErrorResponse: required: - errors - request_id type: object properties: errors: type: array items: $ref: '#/components/schemas/TaskRunError' description: One or more errors that describe what went wrong. request_id: type: string description: Unique identifier for this request, useful for tracing. description: Standard error response. SourceWebsite: required: - url type: object properties: url: type: string description: >- The URL of the website or service. Deck normalizes this on create: it prepends `https://` when no scheme is given, lowercases the scheme and host, drops default ports (80/443), and trims trailing slashes — so the stored and returned value may differ from what you sent. Non-HTTP(S) URLs are rejected. description: Website configuration for a source. SourceHeadersRequest: type: object properties: values: type: object additionalProperties: type: string description: >- Header names mapped to their values (for example, `{ "CF-Access-Client-Id": "a1b2c3.access" }`). Names must be valid HTTP header names and values must be strings. At most 10 entries. `Host`, `Cookie`, `Content-Length`, `Connection`, `Transfer-Encoding`, `User-Agent`, `Origin`, and `Referer` are managed by the browser and cannot be set. tokenized: type: - 'null' - array items: type: string description: >- Optional. Names of the headers in `values` whose values are secret. Tokenized values are vaulted and never returned. required: - values description: >- Request headers Deck attaches to every request to the source's host. Available on Enterprise plans as an add-on. SourceNetworkRequest: type: object properties: type: type: string enum: - default - static_ips description: >- The source's network. `static_ips` runs every run against the source from Deck's [static IP](/platform/static-ips) range. `default` uses Deck's default IPs. required: - type description: >- Network setting for the source. Only `type` can be set; the static IP range is read-only. SourceNetworkResponse: type: object properties: type: type: string enum: - default - static_ips description: 'The source''s network: `default` or `static_ips`.' example: static_ips static_ips: $ref: '#/components/schemas/SourceNetworkStaticIps' description: Present only when `type` is `static_ips`. required: - type description: >- The source's network. Always present; `{ "type": "default" }` on a source without static IPs. SourceHeadersResponse: type: object properties: values: type: object additionalProperties: type: string description: >- Non-tokenized headers returned as name/value pairs in the clear. Tokenized headers are dropped from this map and named in `tokenized` instead. tokenized: type: - 'null' - array items: type: string description: >- Names of the headers whose values were vaulted. Their values never appear in `values` and cannot be read back through the API. Omitted when nothing was tokenized. required: - values description: >- Request headers configured on the source. Secret values are not returned. TaskRunError: required: - type - code - message type: object properties: type: type: string description: >- Error category (e.g. `source`, `auth`, `task`, `rate_limit`). Determines the class of failure. code: type: string description: Machine-readable error code. Use this for programmatic handling. message: type: string description: >- Human-readable explanation. Do not rely on this for logic — it may change. field: type: - 'null' - string description: The input field that caused the error, when applicable. description: Error details for a failed task run. Same structure as API-level errors. SourceNetworkStaticIps: type: object properties: cidr: type: string description: >- The CIDR range to allowlist at the source. The same for every source in your organization. Omitted if the range is temporarily unavailable. example: 203.0.113.0/26 description: The static IP range runs against this source come from. securitySchemes: BearerAuth: type: http description: Secret key (sk_live_...) scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.