POST/v1/push/sources/{source_id}/documents

Send a document (create or replace)

push_upsert_document

Creates or replaces a document by external_id. With JSON, send the content in content (content_type: html, markdown or text, up to 5 MB). With multipart/form-data, send the file in the file part (up to 100 MB, the same formats as a knowledge base upload) and the metadata in the document part (JSON of the same shape without content) or as separate fields external_id, title, url, path, tags. sync_number is the number of the open sync. Without it, the document is written right away (direct upsert), but the next full sync deletes it unless it is sent again. Sending the same document again returns unchanged (idempotent). The document becomes a card at the next sync of the source (within a minute; inside an open sync, after it is closed). Since 1.62.0: card fields (metadata, category, verifiers, verify_interval_days), a file from a multipart upload (upload_id) and attachments (attachments); the response includes status and card_id (the document result). The document limit of a source depends on the plan.

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Path parameters

source_idintegerrequired

Query parameters

sync_numberinteger

Header parameters

Idempotency-Keystring
Key for a safe retry of a write: 1 to 255 printable ASCII characters; a UUID v4 per logical operation is recommended. A retry with the same key within 24 hours does not run the operation again: it returns the saved response (status, headers and body) with the Idempotency-Replayed: true header. The same key with a different method, path, Content-Type or body returns 409 api.idempotency_mismatch; while the first request is still running, 409 api.idempotency_in_progress with Retry-After: 1. After a 5xx or 429 response the key is released, and a retry runs the operation again. The key is scoped to the organization and the caller (API key, user, or custom source key).
length ≥ 1, length ≤ 255

Request body

application/json

Object: PushDocument

external_idstringrequired
Your stable document ID. Sending the same ID replaces the document.
length ≤ 512
titlestringrequired
length ≤ 500
urlstring
Link to the document in your system (http or https).
contentstring
Content (up to 5 MB).
content_typestring
Allowed values: htmlmarkdowntext
Default: "html"
patharray of string | string
Folders of the document: an array of names or a string separated by “/” (up to 10 levels).
permissionsPushPermissions
tagsarray of string
items ≤ 50
author_emailstring
Author. Becomes the owner of the card if this is a Sursa user.
updated_atstring (date-time)
Modification time in your system (part of the document version).
metadataMetadataPatch
metadata of the document's card (since 1.62.0): the object replaces the card's previous one, {} removes all pairs; without the metadata field, the card's metadata does not change.
categorystring
Category of the card: the key of an organization category (GET /v1/categories), since 1.62.0.
length ≤ 64
verifiersPushVerifiers
verify_interval_daysinteger
Verification interval of the card in days (since 1.62.0); without it, the source's interval.
≥ 1, ≤ 3650
upload_idstring
File of the document from a multipart upload (upl_…, since 1.62.0) instead of content. An upload is used once; sending the same document with the same upload_id again does not use it up. While multipart uploads are not available on the installation, the document is rejected with reason file_rejected.
length ≤ 64
attachmentsarray of string
Attachments of the document as multipart uploads (upl_…, since 1.62.0): each becomes its own card of the source with the same folder, permissions and card fields. An attachment missing from a new version of the document is archived.
items ≤ 20

multipart/form-data

filestring (binary)required
documentstring
JSON metadata of the document (the PushDocument fields without content).
external_idstring
titlestring
urlstring
pathstring
tagsstring

Responses

200Written

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.
Idempotency-Replayed
true means the response was replayed from the saved one for this Idempotency-Key: the operation did not run again.

application/json

Object: PushDocumentResult

external_idstringrequired
resultstringrequired
skipped: a document of an atomic batch was not applied because another document was rejected (since 1.62.0).
Allowed values: createdupdatedunchangeddeletednot_founderrorskipped
versionstring
Document version (SHA-256 of the content and metadata).
errorstring
Reason (when result = error).
statusPushDocumentStatusValue
card_idstring | null
Card of the document, if it is already written (since 1.62.0).
reasonPushDocumentReason

400The request is invalid: a parameter value or the state of the object does not allow the action (`detail` is a message).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

404The object does not exist or is not available to you. The API does not confirm that a restricted object exists.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

409The state of the object does not allow the action, for example a duplicate, indexing in progress, or a job that is already processed.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

413The request body exceeds the allowed size.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

415The file format is not supported.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

422Validation error: the body or parameters do not match the schema (`detail` is a list of validation errors), or a parameter value is out of range (`detail` is a message).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

Retry-After
Number of seconds to wait before you retry the request.
RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Safe retries

Send an Idempotency-Key header (for example a UUID) with each POST and PATCH. A retry with the same key within 24 hours returns the saved response instead of running the request again.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← sources · API reference

curl -X POST 'https://api.sursa.com/v1/push/sources/1/documents' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Try it

API key

The key stays in the memory of this tab and is sent only to https://api.sursa.com.

Requests act on the real data of your organization.

Idempotency-Key header

source_id path *

sync_number query

Idempotency-Key

A new key is generated for each request when this is empty.

Request body (JSON)