Get / Update / Delete

Get source details, rename a source or change its default schema, or delete a source — deletion revokes its API key while documents stay in the workspace.

Manage an individual document ingestion source with GET, PATCH, and DELETE operations on /v1/sources/:id. Retrieve source details, update its name or default schema, or permanently delete it. When a source is deleted, its documents are retained but unlinked from the source.

Use GET to inspect a source's current status, document count, and default schema assignment. Use PATCH to rename a source or change its default schema. Use DELETE when a source is no longer needed: this immediately invalidates the source-scoped API key, so any integration using it will start receiving 401 errors.

The GET response includes document_count, default_schema (with its id if set), and the endpoint URL for document ingestion. The status field shows the current state: active, syncing while a connector-based source (Google Drive, SharePoint, etc.) is pulling documents, or error.

Deleting a source retains all its documents in your workspace — they remain accessible via the documents API and any existing extractions are preserved. Only the source-to-document link is removed. Pair GET /v1/sources/:id with GET /v1/sources/:id/documents to see documents belonging to a specific source.

Deleting a source immediately invalidates its API key. Any integration using that key will receive 401 errors. Documents are retained but unlinked from the source.

GET/v1/sources/:id

Response

Response fields

idstringSource UUID.

namestringSource name.

typestringSource type.

statusstringCurrent status.

document_countintegerTotal documents ingested through this source.

default_schemaobject | nullDefault schema or null.

endpointstringDocument ingestion URL.

created_atstringISO 8601 creation timestamp.

linksobjectRelated resource URLs (self, documents, dashboard).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Invoice Pipeline",
  "type": "api",
  "status": "active",
  "document_count": 234,
  "default_schema": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012" },
  "endpoint": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents",
  "created_at": "2024-08-01T09:00:00.000Z",
  "links": {
    "self": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "documents": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents",
    "dashboard": "https://app.talonic.com/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

404not_foundNo source with this ID exists for your organization.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

PATCH/v1/sources/:id

Body parameters

namestringUpdated source name.

default_schema_idstring | nullNew default schema UUID. Set to `null` to remove the default schema.

Request

curl -X PATCH https://api.talonic.com/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Invoice Pipeline v2" }'

Response

Response fields

idstringSource UUID.

namestringUpdated source name.

typestringSource type.

statusstringCurrent status.

document_countintegerTotal documents ingested through this source.

default_schemaobject | nullDefault schema or null.

endpointstringDocument ingestion URL.

created_atstringISO 8601 creation timestamp.

linksobjectRelated resource URLs (self, documents, dashboard).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Invoice Pipeline v2",
  "type": "api",
  "status": "active",
  "document_count": 234,
  "default_schema": null,
  "endpoint": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents",
  "created_at": "2024-08-01T09:00:00.000Z",
  "links": {
    "self": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "documents": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents",
    "dashboard": "https://app.talonic.com/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

403forbiddenThe API key does not have the scope required to update sources.

404not_foundNo source with this ID exists for your organization.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

DELETE/v1/sources/:id

Response

Response fields

deletedbooleanAlways true on success.

idstringID of the deleted source.

Response

{
  "deleted": true,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Errors

Error responses

401unauthorizedMissing or invalid API key.

404not_foundNo source with this ID exists for your organization.

409conflictThe source still has dependent resources that block deletion.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What happens to documents when I delete a source?+

Documents are retained in your organization but unlinked from the deleted source. They remain accessible via the documents API and any existing extractions are preserved.

Does deleting a source revoke its API key?+

Yes. The source-scoped API key is immediately invalidated when the source is deleted. Any subsequent upload attempts using that key will return 401.

Can I change a source's default schema after creation?+

Yes. Send `PATCH /v1/sources/:id` with a new `default_schema_id`, or set it to `null` to remove the default schema. The change applies to documents ingested after the update.