POST/v1/cards/text

Skapa ett textkort (Markdown)

create_text_card

Skapar ett textkort från Markdown (kind=text). Det indexeras på samma sätt som en uppladdad fil. Med async=true köas indexeringen: svaret kommer direkt, och förloppet finns i /v1/jobs.

Autentisering

Skicka en API-nyckel i huvudet Authorization: Authorization: Bearer <nyckel>.

Parametrar i huvuden

Idempotency-Keystring
Nyckel för ett säkert nytt försök med en skrivning: 1–255 utskrivbara ASCII-tecken; ett UUID v4 per logisk åtgärd rekommenderas. Ett nytt försök med samma nyckel inom 24 timmar kör inte åtgärden igen, utan returnerar det sparade svaret (status, huvuden och brödtext) med huvudet Idempotency-Replayed: true. Samma nyckel med en annan metod, sökväg, Content-Type eller brödtext returnerar 409 api.idempotency_mismatch; medan det första anropet fortfarande pågår returneras 409 api.idempotency_in_progress med Retry-After: 1. Efter ett 5xx- eller 429-svar frigörs nyckeln, och ett nytt försök kör åtgärden igen. Nyckeln gäller inom organisationen och för anroparen (API-nyckel, användare eller källnyckel för en egen källa).
length ≥ 1, length ≤ 255
X-View-Asstring
Bara för API-nycklar med rollen admin. Gör anropet som dataprofilen <profile>[:viewer|verifier|editor], till exempel employee:viewer. Installationsnyckeln kan inte använda det här huvudet (403).

Cookie-parametrar

kb_view_asstring
Cookie för läget ”View as” (visa som en annan användare) i en session. POST /auth/view-as sätter den och DELETE /auth/view-as tar bort den.

Anropets brödtext

application/json

Objekt: TextCardRequest

titlestringobligatorisk
length ≥ 1, length ≤ 200
collectionstring
Standard: "default"
body_markdownstring
Kortets text i Markdown; content_type gäller inte för den. Du kan skicka body i stället.
length ≥ 1, length ≤ 500000
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
asyncboolean
Standard: false
bodystring
Kortets text i formatet content_type. Skicka antingen body eller body_markdown; om båda skickas returneras 422 validation.failed.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collection_idinteger | null
Samling efter id. När även collection skickas har collection_id företräde. En samling som inte finns i organisationen eller inte är synlig returnerar 404 collections.not_found.
folder_idstring | null
Mapp i samlingen som kortet ska läggas i, med samma kontroller som folder_id vid filuppladdning. En mapp i en annan samling returnerar 400 folders.card_collection_mismatch, en mapp som saknas returnerar 404 folders.not_found, och utan behörigheten COLLECTION_EDIT_CARDS på mappen returneras 403 authz.forbidden.
length ≤ 64
external_idstring | null
external_id för det nya kortet. Om ett annat kort i organisationen använder det returnerar anropet 409 cards.external_id_taken. Använd PUT /v1/cards-by-external-id/{external_id} för att skapa eller ersätta ett kort efter external_id.
length ≤ 512
metadataMetadataPatch

Svar

200Lyckat svar

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.
Idempotency-Replayed
true betyder att svaret spelades upp från det sparade svaret för denna Idempotency-Key: åtgärden kördes inte igen.

application/json

Objekt: TextCardResult

statusstringobligatorisk
Tillåtna värden: readyerrorskippedqueued
cardCard | nullobligatorisk
tablesinteger
timingsobject
Fält
- total_snumber
errorstring
reasonstring
duplicatetrue
card_idstring | null
job_idinteger
jobJob

400Anropet är ogiltigt: ett parametervärde eller objektets tillstånd tillåter inte åtgärden (`detail` är ett meddelande).

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

401Inga autentiseringsuppgifter skickades (varken en sessionscookie eller en API-nyckel), eller så hittades inte nyckeln.

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

403Åtgärden är inte tillåten: rollen räcker inte, det saknas åtkomst till samlingen eller kortet, anropet körs i läget ”View as” (visa som en annan användare), eller organisationen är avstängd eller borttagen (`detail` är ett objekt med `code: org_suspended | org_deleted`).

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

404Objektet finns inte eller är inte tillgängligt för dig. API:et bekräftar inte att ett begränsat objekt finns.

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

409Objektets tillstånd tillåter inte åtgärden, till exempel en dubblett, en pågående indexering eller ett jobb som redan har bearbetats.

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

422Valideringsfel: brödtexten eller parametrarna stämmer inte med schemat (`detail` är en lista med valideringsfel), eller så ligger ett parametervärde utanför det tillåtna intervallet (`detail` är ett meddelande).

Svarshuvuden

RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

429För många anrop (`api.rate_limited`), organisationens kvot för minuten, dygnet eller månaden är förbrukad (`api.quota_exceeded`; `error.details` innehåller `quota`, `limit` och `reset_at`), organisationens gräns är nådd eller svarstjänsten är upptagen (`answers.engine_busy`). Vänta den tid som anges i huvudet `Retry-After`.

Svarshuvuden

Retry-After
Antal sekunder att vänta innan du skickar anropet igen.
RateLimit-Policy
Gällande gränser i formatet från IETF-utkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerade poster "<name>";q=<quota>;w=<window in seconds>. key är API-nyckelns anropsfrekvens (kvoten är toppen (burst), fönstret är tiden tills den har fyllts på helt; för en session är det user, utan autentiseringsuppgifter ip); minute, day och month är organisationens kvoter för kalenderminuten, kalenderdygnet och kalendermånaden i UTC.
RateLimit
Vad som återstår av varje gräns i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Gränsen för den striktaste posten i RateLimit-Policy (den med minst antal återstående anrop).
X-RateLimit-Remaining
Återstående anrop inom den striktaste gränsen.
X-RateLimit-Reset
Sekunder tills den striktaste gränsen nollställs.

application/json

Objekt: Error

Felkoder

Koder som den här slutpunkten kan returnera i error.code, utöver de allmänna koderna för alla anrop.

Säkra nya försök

Skicka huvudet Idempotency-Key (till exempel ett UUID) med varje POST och PATCH. Ett nytt försök med samma nyckel inom 24 timmar returnerar det sparade svaret i stället för att köra anropet igen.

Hastighetsbegränsningar

Svaren innehåller huvudena RateLimit och RateLimit-Policy samt de tidigare X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset. Ett 429-svar har Retry-After i sekunder: vänta och försök igen.

← cards · API-referens

curl -X POST 'https://api.sursa.com/v1/cards/text' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","collection":"support","body_markdown":"# Refund policy\n\nRefunds are processed within 14 days."}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prova

API-nyckel

Nyckeln finns bara i den här flikens minne och skickas bara till https://api.sursa.com.

Anropen påverkar din organisations riktiga data.

Idempotency-Key header

X-View-As header

Idempotency-Key

Är fältet tomt skapas en ny nyckel för varje anrop.

Anropets brödtext (JSON)