POST/v1/sources

Opret en kilde

create_source

Med en API-nøgle for organisationen (fra 1.62.0) er kun en brugerdefineret kilde (kind: custom) tilgængelig: nøglen skal have rollen admin og scopet admin. Enhver anden type returnerer 400 sources.kind_not_allowed_for_key; connectorer, der logger ind hos udbyderen, sættes op i browseren. Connectorernes felter vises ikke i den offentlige specifikation. En brugerdefineret kilde tager name, samlingen (collection_id eller collection), tilladelsestilstanden permissions_mode, mappen i samlingen til kort (folder_id og folder_mode) og de valgte dokumentmapper (roots). Dokumenter sendes med operationerne /v1/push/sources/{source_id}/*.

Autentificering

Send en API-nøgle i headeren Authorization: Authorization: Bearer <nøgle>.

Headerparametre

X-View-Asstring
Kun for API-nøgler med rollen admin. Udfører anmodningen som dataprofilen <profile>[:viewer|verifier|editor], fx employee:viewer. Installationsnøglen kan ikke bruge denne header (403).
Idempotency-Keystring
Nøgle til et sikkert nyt forsøg på en skrivning: 1 til 255 printbare ASCII-tegn; en UUID v4 pr. logisk operation anbefales. Et nyt forsøg med samme nøgle inden for 24 timer udfører ikke operationen igen: det returnerer det gemte svar (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøgle med en anden metode, sti, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første anmodning stadig kører, 409 api.idempotency_in_progress med Retry-After: 1. Efter et 5xx- eller 429-svar frigives nøglen, og et nyt forsøg udfører operationen igen. Nøglen gælder for organisationen og den kaldende part (API-nøgle, bruger eller nøgle til en brugerdefineret kilde).
length ≥ 1, length ≤ 255

Cookieparametre

kb_view_asstring
Cookie for tilstanden »View as« i en session. POST /auth/view-as sætter den, og DELETE /auth/view-as fjerner den.

Anmodningens brødtekst

application/json

Objekt: SourceCreate

kindstring
Kildens type (se SourceKind); med en organisations API-nøgle kun custom.
Standard: "gdrive"
namestringpåkrævet
length ≥ 1, length ≤ 120
collectionstring
Navnet på kildens samling; du kan angive collection_id i stedet (fra 1.62.0).
length ≥ 1, length ≤ 64
collection_idinteger
Kildens samling efter id (fra 1.62.0); angives begge, har collection_id forrang.
permissions_modestring
Tilstand for tilladelser på kildens kort (fra 1.62.0, som i update_source_settings): own bruger samlingens tilladelser, mirror henter dem fra dokumentet (permissions). Valg af mirror kræver retten til at administrere samlingens tilladelser.
Tilladte værdier: ownmirror
default_owner_idinteger | null
verify_interval_daysinteger
Standard: 90≥ 1, ≤ 3650
tagsarray of string
Standard: []
default_categorystring | null
rootsarray of string | null
Kildens valgte mapper: kun elementer i dem bliver til kort. For en brugerdefineret kilde dokumenternes mappestier (Guides/Billing); for connectors noder i udbyderens træ.
folder_idstring | null
Mappe i kildens samling, som kortene placeres i (null betyder samlingens rod).
folder_modestring
flat placerer alt i den valgte mappe; mirror opretter mapper, der gentager elementets sti i kilden, dog ikke dybere end grænsen for mappeniveauer (3 niveauer; dybere elementer havner i den nærmeste mappe).
Tilladte værdier: flatmirror
Standard: "flat"

Svar

200Vellykket svar

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.
Idempotency-Replayed
true betyder, at svaret blev afspillet igen fra det gemte svar for denne Idempotency-Key: operationen blev ikke udført igen.

application/json

Objekt: DataSource

En af

400Anmodningen er ugyldig: en parameterværdi eller objektets tilstand tillader ikke handlingen (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

404Objektet findes ikke eller er ikke tilgængeligt for dig. API’et bekræfter ikke, at et begrænset objekt findes.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

422Valideringsfejl: brødteksten eller parametrene svarer ikke til skemaet (`detail` er en liste over valideringsfejl), eller en parameterværdi ligger uden for det tilladte interval (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

Retry-After
Antal sekunder, du skal vente, før du prøver anmodningen igen.
RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← sources · API-reference

curl -X POST 'https://api.sursa.com/v1/sources' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"custom","name":"Help center import","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Afprøv

API-nøgle

Nøglen gemmes kun i denne fanes hukommelse og sendes kun til https://api.sursa.com.

Anmodningerne udføres på din organisations rigtige data.

X-View-As header

Idempotency-Key header

Idempotency-Key

Er feltet tomt, genereres en ny nøgle for hver anmodning.

Anmodningens brødtekst (JSON)