Přejít na obsah
Sursa Developers

POST/v1/ask

Získat odpověď asistenta bez streamování

ask

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry hlavičky

  • Idempotency-Keystring

    Klíč pro bezpečné opakování zápisu: 1 až 255 tisknutelných znaků ASCII; doporučuje se UUID v4 pro každou logickou operaci. Opakování se stejným klíčem do 24 hodin operaci znovu nespustí: vrátí uloženou odpověď (stav, hlavičky a tělo) s hlavičkou Idempotency-Replayed: true. Stejný klíč s jinou metodou, cestou, Content-Type nebo tělem vrací 409 api.idempotency_mismatch; dokud první požadavek ještě běží, vrací 409 api.idempotency_in_progress s Retry-After: 1. Po odpovědi 5xx nebo 429 se klíč uvolní a opakování operaci spustí znovu. Klíč platí v rámci organizace a volajícího (klíč API, uživatel nebo klíč vlastního zdroje).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Jen pro klíče API s rolí admin. Provede požadavek jako datový profil <profile>[:viewer|verifier|editor], například employee:viewer. Instalační klíč tuto hlavičku použít nemůže (403).

Parametry cookie

  • kb_view_asstring

    Cookie režimu „View as“ pro relaci. POST /auth/view-as ji nastaví a DELETE /auth/view-as ji smaže.

Tělo požadavku

application/json

Objekt: AskRequest

  • querystringpovinné

    length ≥ 1

  • collectionstring

    Výchozí: "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • toolsboolean | null
  • qualitystring

    Poměr mezi rychlostí a přesností vyhledávání, ze kterého výsledek vychází: fast je rychlejší, precise přesnější. Výchozí: precise.

    Povolené hodnoty: fastprecise

Odpovědi

200Odpověď asistenta. I „bez odpovědi“ je 200, s `empty: no_hits`.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

  • Idempotency-Replayed

    true znamená, že jde o znovu vrácenou uloženou odpověď pro tento Idempotency-Key: operace se znovu nespustila.

application/json

Objekt: AnswerResponse

  • answerstringpovinné
  • question_idintegerpovinné
  • querystring
  • collectionstringpovinné
  • sourcesarray of Sourcepovinné
  • table_queriesarray of TableQuerypovinné
  • datasetsarray of Datasetpovinné
  • chartsarray of ChartSpecpovinné
  • warningsarray of AnswerWarningpovinné
  • timingsTimingspovinné
  • provenancearray of NumberProvenance
  • emptystring

    Povolené hodnoty: no_hitsrestrictedguardrailno_data_for_period

  • basisAnswerBasis
  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • guardrailGuardrailVerdict
  • verified_onlyboolean
  • cachedboolean
  • cache_hitAnswerCacheHit
  • out_of_scopeAnswerOutOfScope
  • attachmentsarray of Attachment
  • export_errorstring
  • toolsstring | null

    Proč byly pro tuto odpověď použity nástroje: request (výslovně vyžádáno); compare, compute, action (podle otázky); needs_calc (je potřeba výpočet nad tabulkami); summary (přehled kolekce nebo dokumentů); mcp (organizace připojila externí servery MCP).

    Povolené hodnoty: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntitypovinné
  • followupsarray of Followuppovinné
  • conversation_idstring

    Jen pro POST /v1/chat s konverzací.

  • answer_idstring

    ID objektu odpovědi.

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

404Objekt neexistuje nebo vám není dostupný. API nepotvrzuje, že objekt s omezeným přístupem existuje.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← answers · Reference API