PUT/v1/cards/{card_id}/content

Substituir el contingut d’una entrada

replace_card_content

Substitueix el contingut de l’entrada per un text nou (application/json, CardContentText: Markdown, HTML o text sense format) o per un fitxer nou (multipart/form-data, CardContentFile, amb les mateixes comprovacions que POST /v1/cards). L’entrada rep una versió nova i es torna a indexar de la mateixa manera que una versió nova d’un fitxer. Es conserven el responsable, les etiquetes, els verificadors i l’interval de verificació, i també una categoria fixada manualment. Canviar el contingut retira la verificació de l’entrada, com fa qualsevol versió nova (motiu update). Un contingut sense canvis no crea cap versió nova (status: skipped, reason: unchanged). Amb async: true, la resposta arriba de seguida amb el treball d’indexació; si no, arriba després de la indexació, com en una pujada. Requereix accés d’escriptura i accés al document sencer (403 cards.content_whole_access). Una entrada que s’està indexant retorna 409 cards.indexing_in_progress. El contingut d’una entrada d’una font només canvia a la seva font (409 cards.managed_by_source).

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de camí

card_idstringobligatori

Paràmetres de capçalera

X-View-Asstring
Només per a claus d’API amb el rol admin. Fa la sol·licitud com el perfil de dades <profile>[:viewer|verifier|editor], per exemple employee:viewer. La clau d’instal·lació no pot fer servir aquesta capçalera (403).

Paràmetres de galeta

kb_view_asstring
Galeta del mode «View as» per a una sessió. POST /auth/view-as l’estableix i DELETE /auth/view-as l’esborra.

Cos de la sol·licitud

application/json

Objecte: CardContentText

bodystringobligatori
Text de l’entrada en el format content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
titlestring | null
Títol nou. Si no es passa, el títol no canvia.
length ≥ 1, length ≤ 200
asyncboolean
true retorna de seguida i indexa l’entrada a la cua; false retorna després de la indexació.
Per defecte: false

multipart/form-data

Objecte: CardContentFile

filestring (application/octet-stream)obligatori
titlestring | null
Títol nou. Si no es passa, el títol no canvia.
length ≤ 200
asyncboolean
Per defecte: false

Respostes

200`queued` (asíncron), `ready` o `error` (síncron), o `skipped` (el contingut no ha canviat).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: UploadResult

statusstringobligatori
Valors permesos: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged o an identical file is already indexed (ja hi ha un fitxer idèntic indexat).
tablesinteger
timingsobject
Camps
- total_snumber
errorstring

400La sol·licitud no és vàlida: el valor d’un paràmetre o l’estat de l’objecte no permeten l’acció (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

402L’organització ha arribat a un límit del pla (entrades, emmagatzematge o usuaris). `error.details` conté `kind`, `limit` i `used`.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

404L’objecte no existeix o no està disponible per a vós. L’API no confirma que existeixi un objecte restringit.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

409L’estat de l’objecte no permet l’acció; per exemple, un duplicat, una indexació en curs o un treball que ja s’ha processat.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

413El cos de la sol·licitud supera la mida permesa.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

415El format del fitxer no és compatible.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

422Error de validació: el cos o els paràmetres no coincideixen amb l’esquema (`detail` és una llista d’errors de validació), o el valor d’un paràmetre és fora de l’interval permès (`detail` és un missatge).

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

Retry-After
Nombre de segons que cal esperar abans de reintentar la sol·licitud.
RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

503Un servei del qual depèn aquesta sol·licitud no està disponible temporalment. Torneu-ho a provar més tard.

Capçaleres de la resposta

RateLimit-Policy
Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.
RateLimit
El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).
X-RateLimit-Remaining
Sol·licituds restants dins del límit més restrictiu.
X-RateLimit-Reset
Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← cards · Referència de l’API

curl -X PUT 'https://api.sursa.com/v1/cards/CARD_ID/content' \
  -H "Content-Type: application/json" \
  -d '{"body":"string"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Provar

Clau d’API

La clau es queda a la memòria d’aquesta pestanya i només s’envia a https://api.sursa.com.

Les sol·licituds actuen sobre les dades reals de la vostra organització.

X-View-As header

card_id path *

Cos de la sol·licitud (JSON)