# Support & Contact
## Technical Emergencies [#technical-emergencies]
If you are experiencing a service outage or critical technical issue, contact our support team directly:
* **Phone:** 0761 76 99 1097
* **Email:** [technik@haufe.de](mailto:technik@haufe.de)
## Not a Customer Yet? [#not-a-customer-yet]
Learn more about Copilot via API and get in touch with our team to explore plans and pricing:
[https://www.haufe.de/angebot/knowledge-as-a-service#form](https://www.haufe.de/angebot/knowledge-as-a-service#form)
# Copilot via API
Welcome to the documentation of **Copilot via API** by Haufe.
Copilot via API lets you bring Haufe expert knowledge into your app, chatbot, or AI workflow.
Send a request to get an AI-generated answer grounded in Haufe content.
## Explore the documentation [#explore-the-documentation]
## Capabilities [#capabilities]
## Why teams choose Copilot via API [#why-teams-choose-copilot-via-api]
## Pricing, plans & rate limits [#pricing-plans--rate-limits]
For information about pricing, available plans, and rate limits, please contact your account partner at Haufe.
## Next Steps [#next-steps]
# Datenschutzerklärung
## Wer sind wir und wie können Sie uns erreichen? [#wer-sind-wir-und-wie-können-sie-uns-erreichen]
Wir, die
Haufe Service Center\
Ein Unternehmen der Haufe Group\
Munzinger Straße 9\
79111 Freiburg\
E-Mail: [Datenschutz-Service@haufe-lexware.com](mailto:Datenschutz-Service@haufe-lexware.com)
sind als Verantwortlicher in Sinne der EU-Datenschutzgrundverordnung (im Folgenden DSGVO genannt) dafür zuständig, Ihre personenbezogenen Daten zu schützen. Bei Fragen zur Datenverarbeitung, zu Ihren Rechten oder zur Datenschutzerklärung steht Ihnen auch unser Konzerndatenschutzbeauftragter Raik Mickler gerne zur Seite. Diesen erreichen Sie unter: [dsb@haufe-lexware.com](mailto:dsb@haufe-lexware.com).
## Welche Daten werden bei der Nutzung unserer Seite verarbeitet? [#welche-daten-werden-bei-der-nutzung-unserer-seite-verarbeitet]
Im Folgenden informieren wir Sie darüber, welche Daten erhoben werden, zu welchen Zwecken diese verarbeitet werden, auf welcher Rechtsgrundlage die Datenverarbeitung erfolgt, welche Möglichkeiten Sie haben, um die Erhebung und Verarbeitung der Daten selbst zu steuern und wann die Daten gelöscht werden.
### Log-Files [#log-files]
**Erhobene Daten:** Beim Aufruf der Webseite werden von Ihrem Browser automatisch folgende Daten übermittelt:
* Ihre IP-Adresse
* Die Webseite, von der Sie kommen,
* Webseiten, die Sie über unsere Seite aufrufen
* Die Seiten, die Sie anklicken, sowie
* Uhrzeit des Seitenaufrufs
* Name Ihres Internet Service Providers
* Ihr Browsertyp und dessen Version
* Das Betriebssystem Ihres Endgeräts
* Das Datum und die Dauer des Besuches. IP-Adressen, die für bösartiges Verhalten (DDoS-Angriffe, Brute-Force-Angriffe u.ä.) genutzt werden, werden von uns gespeichert und gesperrt.
**Zwecke der Datenverarbeitung:** Die vorübergehende Speicherung dieser Daten ist notwendig, um eine Auslieferung der Seite an Ihren Rechner zu ermöglichen und um die Funktionsfähigkeit der Seite sicherzustellen. Mit Hilfe dieser Daten gewinnen wir auch statistische Erkenntnisse darüber, wie unsere Seite genutzt wird. Darüber hinaus erfassen wir die Daten, um unzulässige Zugriffe auf den Webserver und die missbräuchliche Nutzung der Seite rückverfolgen und verhindern zu können und zur Sicherung unserer informationstechnischen Systeme.
**Rechtsgrundlage:** Wir speichern diese Daten vorübergehend auf Grundlage berechtigter Interessen (Art. 6 Abs. 1 f DSGVO). Unser berechtigtes Interesse liegt darin, die vorstehend beschriebenen Zwecke zu erreichen und die Sicherheit unserer Systeme zu gewährleisten.
**Speicherdauer und Steuerungsoptionen:** Die Daten werden gelöscht, wenn sie für die Erreichung der Zwecke nicht mehr notwendig sind. Logfiles werden nach 365 Tagen gelöscht, soweit die Daten nicht aufgrund bösartigen Verhaltens länger gespeichert werden müssen, um die Netzsicherheit zu gewährleisten.
### Allgemeine Informationen zu Cookies und Targeting-Technologien [#allgemeine-informationen-zu-cookies-und-targeting-technologien]
**Erhobene Daten:** Bei Nutzung unserer Seite werden sog. Cookies gesetzt. Hierbei handelt es sich um kleine Textdateien, die auf Ihrem Endgerät abgelegt werden. Cookies enthalten im Regelfall eine charakteristische Zeichenabfolge, die sog. cookieID, mit der Ihr Browser bei einem erneuten Aufruf unserer Seite identifiziert werden kann.
**Zwecke der Datenverarbeitung:** Technisch notwendige Cookies ermöglichen die technische Funktionsweise der Seite. Einige Funktionen unserer Seite können ohne den Einsatz der Cookies nicht angeboten werden.
**Rechtsgrundlage:** Wir setzen technisch notwendige Cookies auf Grundlage berechtigter Interessen ein (Art. 6 Abs. 1 f DSGVO). Unser berechtigtes Interesse liegt darin, das Funktionieren unserer Seite und deren optimale Bedienbarkeit zu gewährleisten.
**Speicherdauer und Steuerungsoptionen:** Einige der von uns verwendeten Cookies werden nach dem Schließen des Browsers wieder automatisch gelöscht (sog. Session Cookies), andere verbleiben dauerhaft auf Ihrem Endgerät und ermöglichen uns, Ihren Browser wiederzuerkennen (sog. Persistente Cookies). Sie haben die volle Kontrolle über die Verwendung von Cookies und können in Ihrem Browser Cookies löschen, das Speichern von Cookies gänzlich deaktivieren oder bestimmte Cookies selektiv akzeptieren. Bitte verwenden Sie die Hilfefunktionen Ihres Browsers, um zu erfahren, wie Sie diese Einstellungen ändern können. Hierdurch kann die Funktionalität unserer Seite eingeschränkt sein.
### Eingesetzte Technologien von Drittanbietern [#eingesetzte-technologien-von-drittanbietern]
## Welche Rechte haben Sie und wie können Sie diese wahrnehmen? [#welche-rechte-haben-sie-und-wie-können-sie-diese-wahrnehmen]
### Widerruf der Einwilligung [#widerruf-der-einwilligung]
Sie können ggf. erteilte Einwilligungen in die Verarbeitung Ihrer personenbezogenen Daten jederzeit mit Wirkung für die Zukunft widerrufen. Bitte beachten Sie, dass der Widerruf keine Auswirkungen auf die Rechtmäßigkeit der bisherigen Datenverarbeitung hat und dass er sich nicht auf solche Datenverarbeitungen erstreckt, für die ein gesetzlicher Erlaubnisgrund vorliegt und die daher auch ohne Ihre Einwilligung verarbeitet werden dürfen.
### Weitere Betroffenenrechte [#weitere-betroffenenrechte]
Darüber hinaus stehen Ihnen nach den Artikeln 15 bis 21 und 77 der EU- Datenschutzgrundverordnung (DSGVO) bei Vorliegen der gesetzlichen Voraussetzungen folgende Betroffenenrechte zu:
1. **Auskunft:** Sie können jederzeit verlangen, dass wir Ihnen Auskunft darüber erteilen, welche Ihrer personenbezogenen Daten wir wie verarbeiten und eine Kopie der von Ihnen gespeicherten personenbezogenen Daten zur Verfügung stellen, Art. 15 DSGVO.
2. **Berichtigung:** Sie können die Berichtigung unrichtiger personenbezogener Daten sowie Vervollständigung unvollständiger personenbezogener Daten verlangen, Art. 16 DSGVO.
3. **Löschung:** Zur Löschung Ihrer personenbezogenen Daten: Bitte beachten Sie, von der Löschung ausgenommen sind Daten, die wir zur Durchführung und Abwicklung von Verträgen und zur Geltendmachung, Ausübung und Verteidigung von Rechtsansprüchen benötigen sowie Daten, für die gesetzliche, aufsichtsrechtliche oder vertragliche Aufbewahrungspflichten bestehen, Art. 17 DSGVO.
4. **Einschränkung der Verarbeitung:** Sie können unter bestimmten Umständen die Einschränkung der Verarbeitung verlangen, z.B. wenn Sie der Ansicht sind, dass Ihre Daten unrichtig sind, wenn die Verarbeitung rechtswidrig ist oder Sie Widerspruch gegen die Datenverarbeitung eingelegt haben. Dies führt dazu, dass Ihre Daten ohne Ihre Einwilligung nur sehr beschränkt verarbeitet werden dürfen, z.B. zur Geltendmachung, Ausübung und Verteidigung von Rechtsansprüchen oder zum Schutz der Rechte anderer natürlicher und juristischer Personen, Art. 18 DSGVO.
5. **Widerspruch gegen die Datenverarbeitung:** Sie haben die Möglichkeit, jederzeit der Datenverarbeitung zu Direktwerbezwecken zu widersprechen. Zudem können Sie bei Vorliegen besonderer Gründe jederzeit den Datenverarbeitungen widersprechen, die auf Grundlage eines berechtigten Interesses erfolgen, Art. 21 DSGVO.
6. **Datenübertragbarkeit:** Sie haben das Recht, die Daten, die Sie uns bereitgestellt haben und die wir auf Grundlage Ihrer Einwilligung oder zur Vertragserfüllung verarbeiten, in einem gängigen, maschinenlesbaren Format zu erhalten und im Rahmen des technisch machbaren eine direkte Übermittlung dieser Daten an Dritte zu verlangen, Art. 20 DSGVO.
### Kontaktwege [#kontaktwege]
Zur Ausübung ihrer Rechte wenden Sie sich bitte an unser Data Protection Operations-Team unter [Datenschutz-Service@haufe-lexware.com](mailto:Datenschutz-Service@haufe-lexware.com).
### Recht auf Beschwerde bei einer Aufsichtsbehörde [#recht-auf-beschwerde-bei-einer-aufsichtsbehörde]
Wenn Sie z.B. der Ansicht sind, dass unsere Datenverarbeitung rechtswidrig ist oder wir die oben beschriebenen Rechte nicht in dem notwendigen Umfang gewährt haben, haben Sie das Recht, bei der zuständigen Datenschutzaufsichtsbehörde Beschwerde einzulegen.
## Allgemeine Hinweise zu Drittlandübermittlungen [#allgemeine-hinweise-zu-drittlandübermittlungen]
Die Erbringung der vertraglich vereinbarten Datenverarbeitung findet ausschließlich in einem Mitgliedsstaat der Europäischen Union (europäischen Rechenzentren) oder in einem anderen Vertragsstaat des Abkommens über den Europäischen Wirtschaftsraum statt. Im Rahmen von Wartungen und Support-Maßnahmen kann es jedoch auch zu Übermittlungen von Daten in den Drittstaat USA kommen. Wir gewährleisten stets ein angemessenes Schutzniveau für die Datenübermittlung, indem wir angemessene Schutzmaßnahmen gemäß Art. 44 ff. DSGVO einführen. Für jede dieser Drittlandübermittlungen wurde mit dem jeweiligen Empfänger ein Vertrag mit Standarddatenschutzklauseln der Europäischen Kommission (Art. 46 Abs. 2 Buchstaben c und d DSGVO) geschlossen.
## Allgemeine Hinweise zu KI [#allgemeine-hinweise-zu-ki]
Wir verarbeiten personenbezogene Daten mittels generativer Künstlicher Intelligenz (KI), um bestehende Geschäftsprozesse zu unterstützen. Der Zweck dieser Verarbeitung entspricht dem Verarbeitungszweck des jeweiligen Geschäftsprozesses, der mit KI unterstützt wird. Die Rechtsgrundlage entspricht ebenfalls der des jeweiligen Geschäftsprozesses. Jedenfalls ist diese Verarbeitung nach Art. 6 Abs. 1 lit. f DSGVO zulässig. Unser berechtigtes Interesse besteht in der effizienten Gestaltung unserer Prozesse durch Automatisierung und darin, unseren Mitarbeitenden eine zeitgemäß Arbeitsunterstützung zur Verfügung zu stellen. Über die Empfänger des jeweiligen Geschäftsprozesses hinaus können beim Betrieb der KI weitere Empfänger innerhalb und außerhalb der Haufe Group, insb. IT-Dienstleister, eingesetzt werden. Zusätzlich zur Speicherdauer des jeweiligen Geschäftsprozesses kann im Einzelfall eine Speicherung bis zu 30 Tage zur Sicherstellung der Cybersicherheit der KI erfolgen. Die personenbezogenen Daten werden nicht zum Training von KI-Modellen durch Dritte verwendet. Wir treffen keine automatisierten Entscheidungen mit KI. Die Kategorien personenbezogener Daten, die verarbeitet werden, entsprechen denen des jeweiligen Geschäftsprozesses.
Stand: September 2026
# Usage Guidelines
When integrating Copilot via API into your application, please follow these guidelines to ensure the best experience for your users and compliance with the terms of use.
## Answer Integrity [#answer-integrity]
Haufe continuously optimizes the AI models powering Copilot via API to deliver the highest quality answers based on expert content. We strongly recommend **not altering or post-processing the API responses** before presenting them to your users.
If responses are modified — for example by summarizing, reformulating, or selectively extracting parts — Haufe can no longer guarantee the accuracy and quality of the information provided.
**Recommendation:** Display the API responses as-is to benefit from Haufe's quality assurance. If you need to adjust formatting for your UI, avoid changing the actual content of the answer.
## Retraining Restrictions [#retraining-restrictions]
API responses **must not** be used for any machine learning purposes. This includes, but is not limited to:
* Fine-tuning or training language models
* Knowledge distillation
* Building training or evaluation datasets
* Any other form of automated learning from the response content
This restriction applies regardless of whether the model training happens internally within your organization or is carried out by a third party.
## Brand Visibility [#brand-visibility]
When displaying answers powered by Copilot via API, you are required to **visibly attribute the content to Haufe**. Users must be able to recognize that the answer originates from Haufe expert content.
Acceptable attribution includes:
* Mentioning **Haufe** by name in proximity to the answer (e.g., "Powered by Haufe" or "Answer generated with Haufe expert content")
* Displaying the **Haufe logo** alongside the response
Your account partner can provide the appropriate logo assets and branding guidelines.
# Build a chatbot
Use the **Threads** mode to build a conversational chatbot where context accumulates over time.
The platform manages conversation history for you — create a thread, send messages, and generate responses.
The AI Copilot evaluates each message in the context of the full conversation history, searches the Haufe knowledge
base, and returns a well-founded answer with source links for further research.
### When to use this [#when-to-use-this]
* **Internal corporate chatbots** that answer employee questions with legally reliable Haufe expert knowledge.
* **Customer-facing assistants** that provide precise, domain-specific answers in areas like Tax or HR.
* **Multi-turn conversations** where users need ongoing, contextual dialogue.
## Next Steps [#next-steps]
# Tailored answers to your document
Upload your own documents — such as contracts, company policies, or other relevant files — and ask questions about them.
Instead of returning a list of search hits, the Haufe Copilot reads the content and gives you a direct,
well-founded answer. You can ask follow-up questions to dig deeper or clarify details, just like in a conversation.
### When to use this [#when-to-use-this]
* **Contract & policy review** — ask targeted questions instead of reading through entire documents.
* **Knowledge extraction** — pull key facts from uploaded files, enriched with Haufe expert knowledge.
* **Combined insights** — merge your own documents with the Haufe knowledge base for comprehensive answers.
### How it works [#how-it-works]
1. Upload one or more documents with your request.
2. The Copilot analyzes your question against the document content and the Haufe expert knowledge base.
3. You receive a precise answer that is grounded in the legally sound Haufe content with source references.
## Next Steps [#next-steps]
# Use as a tool in your agent
Use the **Chat Completions** mode to integrate the Haufe Copilot as a tool within your own AI agent or agentic workflow.
You send a request with the full message history and get a single response.
You have full control over what context is sent with each request, making it easy to integrate the Copilot as one
step in a larger pipeline.
### When to use this [#when-to-use-this]
* **Agent-to-agent communication** where your AI agent queries the Haufe Copilot for domain-specific tasks.
* **Backend workflows** that need on-demand access to expert knowledge in Tax, HR, or other specialist areas.
* **Embedded knowledge** within existing tools such as email clients, ERP systems, or office applications.
## Next Steps [#next-steps]
# Overview
Welcome to the Copilot via API documentation. Here you will find guides covering authentication, API workflows, error handling, and more.
## Where to Start [#where-to-start]
## Next Steps [#next-steps]
# Copilot Usage
## What content does the Copilot API have access to? [#what-content-does-the-copilot-api-have-access-to]
The Copilot draws on a predefined set of content packages. These are the same packages available in Haufe Officeline —
for example, HSO customers can access the content they already know from the Haufe Officeline platform.
## Can I use multiple assistants? [#can-i-use-multiple-assistants]
Yes. If you have access to multiple assistants, you can specify the desired assistant ID when creating a thread or in a chat completions call.
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads \
--header 'api-key: ""' \
--header 'Content-Type: application/json' \
--data '{
"assistant_id": ""
}'
```
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/chat/completions \
--header 'api-key: ""' \
--header 'Content-Type: application/json' \
--data '{
"assistant_id": "",
"messages": [
{ "role": "user", "content": "Your question here" }
]
}'
```
To see which assistants are available to you, call `GET /assistants`.
```bash
curl --request GET \
--url https://api.haufe.ai/agents/v1/assistants \
--header 'api-key: '
```
## Which language models are used, and can they be customized? [#which-language-models-are-used-and-can-they-be-customized]
We evaluate and adopt new language models shortly after their release, following an internal quality review to ensure
our standards are met.
We use a combination of different models, each assigned to specific subtasks following the principle of separation of
concerns. Automated evaluation pipelines and regular manual reviews with domain experts help us select the best model for each task.
We don't offer custom model selection at this time.
## How do sources work? [#how-do-sources-work]
Each response includes a collection of source references at the end. The API returns document identifiers rather than
full URLs, because the final link depends on your specific Haufe Officeline product configuration. You can construct the
link using the following [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-1.1) URL template:
```
https://products.haufe.de/{license_id}/document/{app_doc_id}{?auth_realm}
```
* `license_id` — the product ID (PI) of your specific product
* `app_doc_id` — the document identifier returned by the API
* `auth_realm` — the authentication realm (e.g., `haufepublic`) that determines which authentication provider is used
To view the original source document, follow the constructed link and sign in to your Haufe Officeline product via SSO.
For questions about your `product ID` or `auth_realm`, contact your account representative.
## Are inline citations or footnotes supported? [#are-inline-citations-or-footnotes-supported]
Inline source attribution (footnotes) is planned. We don't have a specific timeline yet.
## Can I use API responses to train or fine-tune my own models? [#can-i-use-api-responses-to-train-or-fine-tune-my-own-models]
No. You must not use Copilot via API responses for any machine learning purposes — including model training, fine-tuning, knowledge distillation, or building training datasets. See our [Usage Guidelines](/usage-guidelines#retraining-restrictions) for details.
## Can I see how many requests a customer makes via the API? [#can-i-see-how-many-requests-a-customer-makes-via-the-api]
Yes. We plan to make this information available through our developer portal.
## Next Steps [#next-steps]
# Data & Privacy
## Can the storage of user questions be disabled? [#can-the-storage-of-user-questions-be-disabled]
We store conversation history to maintain chat context across messages. Without it, we cannot provide multi-turn chat
functionality.
We do offer data anonymization. For example, the service can replace email addresses and IBANs entered in the chat with
placeholders. The set of anonymized entity types is part of the configuration of each Copilot. See the [Anonymization](/docs/guides/anonymization) guide for details.
For more information on how to manage stored data, see the [Data Deletion](/docs/guides/data-deletion) guide.
## Is our data used to train language models? [#is-our-data-used-to-train-language-models]
No. Your data is never used to train any language model. We use third-party LLM providers such as OpenAI and Azure OpenAI, and all API usage is governed by enterprise agreements that explicitly prohibit using customer data for model training.
## After how long are threads deleted? [#after-how-long-are-threads-deleted]
Threads are not automatically deleted. Use the [`DELETE /threads/:thread_id`](/api-reference/threads/delete_thread_v1_threads__thread_id__delete) endpoint to delete a thread
manually.
## Next Steps [#next-steps]
# Overview
Find answers to common questions about the Copilot API below. Questions are grouped by topic.
## Next Steps [#next-steps]
# Integration
## Are there technical requirements to use the API? [#are-there-technical-requirements-to-use-the-api]
The API follows REST best practices and authenticates via API key or via OAuth user tokens. It integrates with any HTTP-capable platform —
including workflow automation tools like Microsoft Power Automate.
See the [Authentication](/docs/getting-started/authentication) guide to get started.
## Next Steps [#next-steps]
# Troubleshooting
## The copilot says it does not have enough information to answer my query, although it should. [#the-copilot-says-it-does-not-have-enough-information-to-answer-my-query-although-it-should]
Please check that you have provided the `license_id` in the `meta_data.user_data.licence` field of your request.
Without a valid license, the assistant cannot access the relevant content packages.
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads/{thread_id}/run \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"assistant_id": "",
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/chat/completions \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"assistant_id": "",
"messages": [
{ "role": "user", "content": "Your question here" }
],
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
## I get "invalid username or password" when logging in to the Developer Portal. [#i-get-invalid-username-or-password-when-logging-in-to-the-developer-portal]
This error appears when your account has not yet been validated. After registration, a Haufe contact person needs to approve your account before you can log in. The error does not mean your credentials are wrong.
Please wait for the validation confirmation before trying again. See [Developer Portal – Account validation](/docs/getting-started/developer-portal#account-validation) for more details.
## My request with an OAuth access token gets 401. [#my-request-with-an-oauth-access-token-gets-401]
The gateway answers `{"message": "Unauthorized", "http_status_code": 401}` when the `Authorization` header is missing, the token is expired, revoked, or not valid, or the client has no active subscription.
Refresh the token and retry once. If the refresh fails, send the user through the login again.
If every token of your client gets a 401, contact your Haufe contact person to check the subscription of your application.
See [OAuth: Let Your Users Log In with Haufe – Error Codes](/docs/guides/oauth#error-codes) for details.
## Next Steps [#next-steps]
# Authentication
Copilot via API supports two authentication methods. Your Haufe contact person sets up the method that fits your use case.
The header you send depends on the method.
| Method | Use it when | Header |
| ---------------- | ------------------------------------------------------------------------------------- | -------------------------------------- |
| API key | Your application calls the API in its own name. You use one key for your application. | `api-key: ` |
| OAuth user token | Haufe users log in through your product and use their own content package. | `Authorization: Bearer ` |
Send exactly one of the two headers with every request.
Use the OAuth user login when the person who uses your product has their own Haufe account and license.
Use the API key when they do not.
## API Key [#api-key]
### How to Get Your API Key [#how-to-get-your-api-key]
Your API key is provided by your Haufe contact person. You can view and rotate it in the [Developer Portal](/docs/getting-started/developer-portal).
### Using Your API Key [#using-your-api-key]
Include your API key in the `api-key` header of every request:
```bash
curl --request GET \
--url https://api.haufe.ai/agents/v1/assistants \
--header 'api-key: '
```
## OAuth User Login [#oauth-user-login]
Your users log in with their Haufe account through your product. Your backend exchanges the login for an access token and sends it as a bearer token:
```bash
curl --request GET \
--url https://api.haufe.ai/agents/v1/assistants \
--header 'Authorization: Bearer '
```
The guide [OAuth: Let Your Users Log In with Haufe](/docs/guides/oauth) describes how you get your client credentials and how you run the login flow.
It also lists the errors to expect.
## Next Steps [#next-steps]
# Developer Portal
The Developer Portal at [portal.haufe.ai](https://portal.haufe.ai) is your central hub for managing your integration with the Haufe Copilot via API. It provides:
* **API status and usage** (WIP) — Monitor availability and track your current consumption at a glance.
* **Credential management** — View and rotate your API keys or OAuth client secrets.
* **Team access** — Invite team members so they can access the same application and collaborate.
* **Documentation** — Access the full [API documentation](/docs/getting-started) directly from the portal.
## Registration [#registration]
Access to the Developer Portal requires an active service agreement with Haufe. If you are interested in using the Haufe Copilot via API, please reach out to your Haufe contact person or our product management team to discuss your use case and get started.
### Register at portal.haufe.ai [#register-at-portalhaufeai]
Once your access has been confirmed, you can create your account. Enter your first name, last name, and email address in the registration form and click **Sign Up**.
After submitting, you will see a confirmation screen. Your request is now pending review by the Haufe team.
### Account validation [#account-validation]
Your account will not be active immediately.
A Haufe contact person needs to approve your registration before you can log in and use the portal.
Once validated, we will assign your application to your account.
You will receive an email confirming the activation, and your application will be visible in the portal as soon as you log in.
If you try to log in before your account has been approved, you will see an **"Invalid username or password"** error.
This does not mean your credentials are wrong — it means your account has not yet been validated.
You will receive an e-mail as soon as it has been validated.
If this persists, please reach out to your Haufe contact person.
## How to use the portal [#how-to-use-the-portal]
Your account can have multiple **applications**. Each application contains one or more **subscriptions**.
A subscription grants access to a specific API and defines its rate limits.
Applications and subscriptions are assigned by the Haufe team.
### Accessing Applications [#accessing-applications]
Navigate to the **Applications** tab to see all applications assigned to your account.
If you do not see any applications after logging in, reach out to your Haufe contact person to have a subscription assigned.
### Subscriptions and API keys [#subscriptions-and-api-keys]
Select an application to view its subscriptions. Each subscription shows the API it provides access to, its status, and the associated API key. You can also rotate your API key here if needed.
### OAuth applications [#oauth-applications]
If your application authenticates with [OAuth user tokens](/docs/guides/oauth), it has no API key.
The application settings show the client ID and the client secret instead. You can renew the client secret and edit the redirect URIs there.
## Next Steps [#next-steps]
# Overview
Welcome to the Copilot via API documentation. Here you will find guides covering authentication, API workflows, error handling, and more.
## Where to Start [#where-to-start]
## Next Steps [#next-steps]
# Quickstart
Get started with **Copilot via API** in minutes. This guide walks you through the basic flow of generating a response using Copilot via API.
## Basic Flow [#basic-flow]
Conceptually, you will:
1. Retrieve available assistants.
2. Create a **thread**, which represents a conversation between a user and an assistant.
3. Attach one or more **user messages** to this thread.
4. **Run** the thread to generate an assistant message.
5. Optionally retrieve all messages in the thread.
For additional operations (e.g. deleting threads), refer to the [API Reference](/api-reference).
The examples use the `api-key` header. If you authenticate with [OAuth user tokens](/docs/guides/oauth), send `Authorization: Bearer ` instead.
***
## Step 1: Retrieve Available Assistants [#step-1-retrieve-available-assistants]
Copilot via API offers various assistants specialized in different domains such as Tax, HR, and Sustainability.
Use this endpoint to retrieve all available assistants and their associated metadata structure.
```bash title="List available assistants"
curl --request GET \
--url https://api.haufe.ai/agents/v1/assistants \
--header 'api-key: '
```
The response contains the list of available assistants and their metadata structures. For full data type definitions,
refer to the [API Reference](/api-reference).
***
## Step 2: Create a Thread [#step-2-create-a-thread]
To start a conversation with an assistant, create a new thread:
```bash title="Create a thread"
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"assistant_id": "",
"user_id": "",
"title": "First Thread Example"
}'
```
`user_id` is optional but useful if you need to track which end user created the thread. To keep PII out of our systems, prefer an opaque identifier (e.g. a UUID) rather than an email or name.
The response contains the `id` of the created thread, referred to as `thread_id` in the following steps.
***
## Step 3: Attach User Messages [#step-3-attach-user-messages]
After creating a thread, attach one or more user messages to it:
```bash title="Create a message in the thread"
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads/:thread_id/messages \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"role": "user",
"content": ""
}'
```
* Replace `:thread_id` with the `id` from the *Create a thread* response.
* You can add multiple user messages by calling this endpoint multiple times.
* Each message must include `role` (must be `"user"`) and `content` (max 30,000 characters).
* Only **user messages** are allowed. Attempting to add assistant messages manually will result in an error.
***
## Step 4: Generate an Assistant Message (Run) [#step-4-generate-an-assistant-message-run]
Trigger generation of an assistant response by running the thread:
```bash title="Generate an answer"
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads/:thread_id/run \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
The payload requires valid metadata, including a license ID under `meta_data.user_data.licence`.
The value must be one of the **allowed license IDs** provided by your Haufe contact person.
An invalid or mismatching license ID may degrade response quality but typically does not raise an error.
* This endpoint shares rate limits with other answer-generation operations (`/run`, `/run/stream`). See [Rate Limits](/docs/guides/rate-limits).
* To receive the response incrementally, use the streaming variant: `POST /agents/v1/threads/:thread_id/run/stream`.
The response contains an `AssistantMessage` with the generated answer and corresponding metadata.
***
## Step 5: Retrieve Messages [#step-5-retrieve-messages]
You can retrieve all messages in a thread, including user and assistant messages:
```bash title="Get all messages"
curl --request GET \
--url https://api.haufe.ai/agents/v1/threads/:thread_id/messages \
--header 'api-key: '
```
The endpoint is paginated and returns messages sorted by creation time (newest first).
## Next Steps [#next-steps]
# Anonymization
Copilot via API can anonymize personally identifiable information (PII) in messages to protect user privacy.
## Overview [#overview]
Messages that you attach to a thread or send via the Chat-Completions API can contain PII.
When anonymization is configured, the service detects PII before it processes a message. Detection uses a combination of static pattern matching and named-entity recognition (NER). Then the service replaces each detected entity with a placeholder tag.
The following entity types can be anonymized:
| Entity Type | Placeholder |
| ------------------------------ | ---------------------- |
| Email addresses | `` |
| Phone numbers | `` |
| IBANs | `` |
| Credit card numbers | `` |
| German tax IDs | `` |
| German social security numbers | `` |
For example, the service replaces an email address with `` and a tax ID with ``. Downstream services only see the anonymized form.
The set of entity types is part of the configuration of each Copilot. The configurations range from no anonymization to all entity types in the table above.
We conclude a data processing agreement (German: Auftragsverarbeitungsvertrag, AVV) with each customer to protect personal data that messages can contain.
Even though PII is anonymized, we strongly recommend that your users share only the minimum personal information necessary in their messages.
## Names and birthdates [#names-and-birthdates]
The service can also detect names (``) and birthdates (``). We do not anonymize these entity types by default. The false positive rate within Haufe content is high. For example, European laws are referred to by names.
## Data deletion [#data-deletion]
When you delete a thread, the service does not anonymize the messages. It redacts the content of every message. See [Data Deletion](/docs/guides/data-deletion) for details.
## Next Steps [#next-steps]
# Data Deletion
Calling the `DELETE /threads/:thread_id` endpoint marks the thread as deleted. The thread becomes inaccessible immediately: a later read returns a `ThreadDeactivated` error.
Any user information attached to the thread (if provided) is replaced with a generic placeholder. The content of every message in the thread is then **redacted**: each content field is replaced with ``. The message content is gone — it is not pseudonymized, and it cannot be recovered.
Redaction runs in the background, so a `204 No Content` confirms that the thread is deleted and the redaction is scheduled, not that it has already finished. It normally follows within seconds. The thread is inaccessible in either case, so the delay is not observable through the API.
The thread and its messages stay in the database so that usage statistics keep working. What remains is the telemetry: the thread, the assistant, the number of messages, and the timestamps.
Redaction replaces the earlier behaviour, where a deletion applied an anonymization pass to the thread's messages. An anonymization pass removes identifiers such as names and addresses, but it leaves the surrounding context in place. Redaction removes the content itself.
Redaction keeps the shape of the message intact. A message still returns the same content-block structure with the same block types; only the content fields carry ``.
Anonymization still applies to messages in threads you have **not** deleted, when it is active in the assistant's configuration. For more details on how it works, see [Anonymization](/docs/guides/anonymization).
## Next Steps [#next-steps]
# Deep Agent
Deep Agent is currently under development phase.
**Deep Agent** streams responses as typed content blocks instead of plain text. Each chunk exposes what the agent is doing internally - reasoning, tool calls
executed inline, or the final answer - in real time.
The events/stream endpoints are dedicated to assistants that stream content\_blocks e.g. Deep Agent -
streams `content_blocks` instead of plain text. In addition, what is specific to Deep Agent is the `server_tool_call`
/ `server_tool_result` block pair: Deep Agent executes tools itself within the same turn and reports the trace
inline, whereas other assistants that call tools emit a `tool_call` block and expect the caller to execute it and
return the result as a separate tool message.
## Endpoints [#endpoints]
Deep Agent is available on both the **Threads** and **Chat Completions** APIs:
| Mode | Endpoint |
| ---------------- | ------------------------------------------------ |
| Threads | `POST /v1/threads/{thread_id}/run/events/stream` |
| Chat Completions | `POST /v1/chat/completions/events/stream` |
Both endpoints return the same NDJSON response format (one JSON object per line) with identical content block types. The only difference is how you provide the conversation context — thread ID vs. inline messages.
The request body is identical to the corresponding regular stream endpoint (`/run/stream` or `/chat/completions/stream`).
## Content Block Types [#content-block-types]
Each chunk's `delta.content_blocks` is a list of content blocks. A single chunk typically contains one block.
| Type | Key field(s) | Description |
| -------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `text` | `text` | A fragment of the final answer text. |
| `reasoning` | `reasoning` | Internal thinking produced before the answer. |
| `tool_call` | `name`, `args`, `id` | A tool invocation the caller must execute and answer with a separate tool message. |
| `server_tool_call` | `name`, `args`, `id` | **Deep Agent only.** A tool invocation the agent executes itself, inline, within the same turn. |
| `server_tool_result` | `tool_call_id`, `status`, `output` | **Deep Agent only.** The result of a preceding `server_tool_call`. `status` is `success` or `error`. |
Blocks arrive in the order they are produced by the agent.
## Response Shape [#response-shape]
Each NDJSON line looks like this:
```json
// server_tool_call
{
"message_id": "969b216f-605f-44f4-9df9-cc43e56326fd",
"thread_id": "...",
"created_at": "...",
"delta": {
"role": "assistant",
"content_blocks": [
{
"type": "server_tool_call",
"name": "human_resource_search_tool",
"args": { "user_query": "wiederholtes Zuspätkommen Abmahnung verhaltensbedingte Kündigung" },
"id": "call_pjGaby08YGRYEOVdqQtcIYRj"
}
],
"sources": []
}
}
// server_tool_result
{
"message_id": "969b216f-605f-44f4-9df9-cc43e56326fd",
"thread_id": "...",
"created_at": "...",
"delta": {
"role": "assistant",
"content_blocks": [
{
"type": "server_tool_result",
"tool_call_id": "call_pjGaby08YGRYEOVdqQtcIYRj",
"status": "success",
"output": "
# Error Handling
This guide covers error handling for Copilot via API.
## Response Structure [#response-structure]
All error responses share a consistent JSON structure:
```json
{
"error_code": "",
"detail": ""
}
```
* `error_code` — a stable string identifier for the error type. Use this in your error handling logic.
* `detail` — a human-readable description. Treat this as informational; do not rely on it programmatically.
This structure is returned for all errors, including unexpected ones. If an unhandled error occurs, the API returns HTTP `500` with a generic `error_code` and `detail` rather than exposing internal details.
## Gateway Errors [#gateway-errors]
The API gateway rejects a request before it reaches the API when the credentials are missing or invalid. These responses have a different structure:
```json
{
"message": "Unauthorized",
"http_status_code": 401
}
```
| HTTP Status | Meaning | Cause |
| ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 | Unauthorized | The request has no `api-key` or `Authorization` header, the API key is unknown, the access token is expired, revoked, or not valid, or the OAuth client has no active subscription. |
See [Authentication](/docs/getting-started/authentication) for the header of each authentication method.
## HTTP Errors [#http-errors]
The table below lists the possible HTTP status codes, their meanings, and example response bodies.
| HTTP Status | Meaning | Response |
| ----------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Bad Request - Content Filter | `{"error_code": "content_filter_error", "detail": "Could not parse ..."}` |
| 400 | Bad Request | `{"error_code": "bad_request", "detail": "OpenAI API request was invalid."}` |
| 400 | Length Filter | `{"error_code": "length_finish_reason_error", "detail": "OpenAI length filter finished with an error."}` |
| 400 | Request Metadata Missing | `{"error_code": "request_metadata_missing_or_incomplete", "detail": "Request lacks required request metadata"}` |
| 401 | Unauthorized | `{"error_code": "unauthorized", "detail": "Missing or invalid API key"}` |
| 403 | Permission Denied | `{"error_code": "permission_denied", "detail": "OpenAI API request was denied permission."}` |
| 403 | Assistant Not Licensed | `{"error_code": "assistant_not_licensed", "detail": "The access token has no licensed product for this assistant"}` |
| 409 | Conflict | `{"error_code": "conflict_error", "detail": "OpenAI API request resulted in a conflict."}` |
| 422 | Unprocessable Entity | `{"error_code": "unprocessable_entity", "detail": "OpenAI API request was unprocessable."}` |
| 422 | User ID Conflicts With Token | `{"error_code": "user_id_conflicts_with_token", "detail": "The user_id in the request differs from the user of the access token"}` |
| 429 | Too Many Requests | `{"error_code": "rate_limit_error", "detail": "OpenAI API request rate limit exceeded."}` |
| 500 | API Timeout | `{"error_code": "api_timeout_error", "detail": "OpenAI API request timed out."}` |
| 500 | API Connection Error | `{"error_code": "api_connection_error", "detail": "OpenAI API request connection error."}` |
| 500 | API Error | `{"error_code": "api_error", "detail": "OpenAI API request resulted in an error."}` |
| 500 | Attachment Not Stored | `{"error_code": "attachment_persistence_mismatch", "detail": "The attachment could not be stored due to an internal error."}` |
The errors `request_metadata_missing_or_incomplete`, `assistant_not_licensed` and `user_id_conflicts_with_token` come from the API itself. See [Request Metadata Validation](/docs/validation/metadata) and the [OAuth guide](/docs/guides/oauth) for their causes.
### Example [#example]
```json
{
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter"
}
```
## Rate Limit Errors (HTTP 429) [#rate-limit-errors-http-429]
When you exceed a rate limit, the API returns HTTP `429` with the following body:
```json
{
"detail": "Rate Limit Exceeded"
}
```
The response also includes headers to help you implement retry logic:
| Limit Breached | Header | Value |
| -------------- | -------------------------- | --------------------------------------------------- |
| Per-second | `Retry-After-Milliseconds` | Milliseconds until the current second window resets |
| Per-second | `X-Rate-Limit-Second` | Your allowed requests-per-second limit |
| Per-minute | `Retry-After-Seconds` | Seconds until the current minute window resets |
| Per-minute | `X-Rate-Limit-Minute` | Your allowed requests-per-minute limit |
Use the `Retry-After-Milliseconds` or `Retry-After-Seconds` header value to wait before retrying. Implement exponential backoff for repeated 429 responses.
For the applicable rate limits, see the [Rate Limits](/docs/guides/rate-limits) guide.
## Errors During Streaming [#errors-during-streaming]
When an error occurs during a streaming response, the stream will include all chunks generated up to the point of the error, followed by a final chunk containing the error details and finish reason in the `meta_data` field.
### Example [#example-1]
```json
{
"message_id": "00000000-0000-0000-0000-000000000001",
"thread_id": "00000000-0000-0000-0000-000000000001",
"created_at": "2024-11-15T17:43:37.443794",
"delta": {
"role": "assistant",
"content": "Die",
"sources": [],
"meta_data": null
}
}
{
"message_id": "00000000-0000-0000-0000-000000000001",
"thread_id": "00000000-0000-0000-0000-000000000001",
"created_at": "2024-11-15T17:43:37.446459",
"delta": {
"role": "assistant",
"content": "",
"sources": [],
"meta_data": {
"type": "common_metadata",
"finish_reason": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
}
}
}
```
If an error occurs during streaming, the message is **not** persisted — even if you already received a `message_id` in the stream.
## Next Steps [#next-steps]
# LLM-Friendly Documentation
This documentation site exposes machine-readable endpoints that let you feed the full documentation into Large Language Models (LLMs). Use these endpoints to summarize the docs, ask questions about the API, or build tools on top of the documentation.
## Available Endpoints [#available-endpoints]
### `/llms.txt` — Table of Contents [#llmstxt--table-of-contents]
Returns a structured list of all documentation pages with titles, URLs, and descriptions. Use this as a starting point to discover available content or to let an LLM decide which pages to read.
```
GET /llms.txt
```
Full URL:
**Example response:**
```markdown
# Overview
- [Getting Started](/): Overview of Copilot via API.
# Documentation
- [Quickstart](/docs/getting-started/quickstart): Make your first API call in minutes.
- [Overview](/docs/guides/overview): Threads vs Chat Completions.
...
```
### `/llms-full.txt` — Full Documentation [#llms-fulltxt--full-documentation]
Returns the entire documentation — all pages from Overview, Documentation, and API Reference — concatenated into a single plain-text document. This is useful when you want to provide the full context to an LLM in one request.
```
GET /llms-full.txt
```
Full URL:
The full document can be large. Make sure your LLM's context window can handle the content, or use `/llms.txt` to discover available pages first.
## Use Cases [#use-cases]
* **Summarization** — Pass `/llms-full.txt` to an LLM and ask for a summary of the entire API surface.
* **Q\&A** — Use `/llms-full.txt` or selected pages as context to answer developer questions about the API.
* **Code Generation** — Give an LLM the API reference pages to generate client code or integration examples.
* **Internal Tooling** — Build search, chatbots, or onboarding tools that use the documentation as a knowledge base.
## Next Steps [#next-steps]
# MCP Integration
The **MCP** lets any MCP-compatible AI agent or workflow call Haufe Copilot tools
directly — without building a REST integration. Once configured, your agent can invoke specialized copilots
(Tax, HR, Sustainability, Real Estate, Finance, Law, ...) as native tools.
**An update is on the way.** We will release a new version of the MCP integration soon.
The way you use the MCP server changes with that version. This page describes the current version.
The MCP server shows you only the tools that your API key can use. The table in
[Available Tools](#available-tools) is the full catalog. You see the part of the catalog that matches your
subscription and your licenses.
## Quick Start [#quick-start]
**Endpoint** `https://api.haufe.ai/agents/v1/mcp`
**Transport** Streamable HTTP
**Required HTTP headers:**
| Header | Value | Required |
| --------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `api-key` | Your API key — get one from the [Developer Portal](/docs/getting-started/developer-portal) | Always |
| `license-id-tax` | Tax license ID (from your Haufe contact) | Only when calling the Tax tool |
| `license-id-hr` | HR license ID | Only when calling the HR tool |
| `license-id-sustainability` | Sustainability license ID | Only when calling the Sustainability tool |
| `license-id-re` | Real Estate license ID | Only when calling the Real Estate tool |
| `license-id-finance` | Finance license ID | Only when calling the Finance tool |
| `license-id-law` | Law license ID | Only when calling the Law tool |
**Claude Code config (`.mcp.json`):**
Only include the `license-id-*` headers for the copilots you want to use and have access to — omit the rest.
```json title=".mcp.json"
{
"mcpServers": {
"haufe-copilot": {
"type": "http",
"url": "https://api.haufe.ai/agents/v1/mcp",
"headers": {
"api-key": "",
"license-id-tax": "",
"license-id-hr": "",
"license-id-sustainability": "",
"license-id-re": "",
"license-id-finance": "",
"license-id-law": ""
}
}
}
}
```
Restart your MCP client and the copilot tools will appear in the tool list. See [Python MCP SDK](#python-mcp-sdk) below for a non-Claude example.
A call to a copilot that is not enabled for your API key fails with
`Your API key has no access to the tool ...`. Ask your Haufe contact to enable more copilots.
License IDs are validated per tool call. Calling a tool without the corresponding license header will result in an authentication error.
MCP tool calls count against your answer-generation rate limit — see [Rate Limits](/docs/guides/rate-limits).
## Available Tools [#available-tools]
The table below is the full catalog of copilot tools. Each tool accepts a single
`user_message` argument and returns a JSON-encoded assistant response.
| Tool name | Domain | License header required |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `haufe_copilot_tax_tool` | German tax law (income tax, VAT, corporate tax, payroll tax, trade tax) | `license-id-tax` |
| `haufe_copilot_hr_tool` | German employment & HR law (contracts, dismissal, works council) | `license-id-hr` |
| `haufe_copilot_sustainability_tool` | ESRS standards, CSRD directive, ESG compliance | `license-id-sustainability` |
| `haufe_copilot_real_estate_tool` | German real estate law (tenancy, WEG, landlord/tenant rights) | `license-id-re` |
| `haufe_copilot_finance_tool` | German accounting & financial reporting (Rechnungswesen: bookkeeping, Bilanzierung, Jahresabschluss, VAT, controlling) | `license-id-finance` |
| `haufe_copilot_law_tool` | German law across \~15 practice areas (labor, family & inheritance, corporate, tenancy/property, traffic, fee law, case law) | `license-id-law` |
## Python MCP SDK [#python-mcp-sdk]
```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
async with streamablehttp_client(
"https://api.haufe.ai/agents/v1/mcp",
headers={
"api-key": "",
"license-id-tax": "",
},
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"haufe_copilot_tax_tool",
{"user_message": "Was sind die Fristen für die Steuererklärung?"},
)
print(result.content[0].text)
asyncio.run(main())
```
## Tool Response Format [#tool-response-format]
Each tool returns a JSON string. Parse it to access the structured response:
```python
import json
raw = result.content[0].text
response = json.loads(raw)
print(response["content"]) # main answer text
print(response["sources"]) # list of cited sources
```
The response schema matches the `AssistantMessage` returned by the Chat Completions endpoint.
## Next Steps [#next-steps]
# OAuth: Let Your Users Log In with Haufe
You like to integrate a Haufe copilot into your own product. Your users have a Haufe account.
They log in with that account inside your product.
Your backend then calls Copilot via API with the access token of the user.
The content package of the user decides which content the copilot can use for the answer.
This page describes how you get your OAuth client, how you run the login flow, and how you send the token.
If your application calls the API in its own name, use an [API key](/docs/getting-started/authentication) instead.
## How It Works [#how-it-works]
1. Your backend redirects the user to the Haufe login.
2. The user logs in with their Haufe account and returns to your redirect URI with an authorization code.
3. Your backend exchanges the code for an access token and a refresh token.
4. Your backend sends the access token as a bearer token to Copilot via API.
5. The API checks the signature and the expiry of the token and the subscription of your client.
6. The API reads the content package of the user from the token, then answers the request.
The flow is the standard OAuth 2.0 authorization code flow with PKCE.
The browser of the user never sees a token. Keep the client secret and all tokens on your backend.
## Get Your Client ID and Client Secret [#get-your-client-id-and-client-secret]
### Send your redirect URI to Haufe [#send-your-redirect-uri-to-haufe]
The redirect URI is the endpoint of your backend that receives the authorization code, for example `https://app.example.com/auth/callback`.
Use an `https` URI in production. For local tests, `http` URIs are accepted for `localhost` and loopback addresses only, for example `http://localhost:9999/callback`.
We recommend a separate application for local tests. Then the client secret of your production application stays on your backend.
Your Haufe contact person creates the OAuth application with this URI and assigns it to your account.
### Read your credentials in the portal [#read-your-credentials-in-the-portal]
Open the application in the [Developer Portal](/docs/getting-started/developer-portal). The settings show the **client ID** and the **client secret**.
**Renew client secret** creates a new secret. The old secret stops working immediately.
### Manage your redirect URIs in the portal [#manage-your-redirect-uris-in-the-portal]
You can add and remove redirect URIs in the application settings. Save the application after the change.
The client ID and the client secret stay the same after a save.
Treat the client secret like a password. Store it on your backend only. Never ship it in a browser or mobile app.
## Run the Login Flow [#run-the-login-flow]
The Haufe login is an OpenID Connect provider. Use an OpenID Connect library for your platform and configure it with these values.
Most libraries read the endpoints from the discovery document at `https://iam.auth.haufe.io/.well-known/openid-configuration`.
| Setting | Value |
| ---------------------- | ---------------------------------------------- |
| Issuer | `https://iam.auth.haufe.io` |
| Authorization endpoint | `https://iam.auth.haufe.io/oauth/v2/authorize` |
| Token endpoint | `https://iam.auth.haufe.io/oauth/v2/token` |
| Grant type | `authorization_code` with PKCE (`S256`) |
| Client authentication | `client_secret_basic` |
| Scopes | `openid profile email offline_access` |
The scope `offline_access` gives you a refresh token. Without it, the user must log in again when the access token expires.
### Redirect the user to the authorization endpoint [#redirect-the-user-to-the-authorization-endpoint]
```text title="Authorization request"
https://iam.auth.haufe.io/oauth/v2/authorize
?response_type=code
&client_id=
&redirect_uri=https://app.example.com/auth/callback
&scope=openid%20profile%20email%20offline_access
&state=
&code_challenge=
&code_challenge_method=S256
```
The user logs in with their Haufe account. The login then redirects the browser to your redirect URI with the query parameters `code` and `state`.
Check that `state` matches the value you sent.
### Exchange the code for tokens [#exchange-the-code-for-tokens]
```bash title="Token request"
curl --request POST \
--url https://iam.auth.haufe.io/oauth/v2/token \
--user ':' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'code=' \
--data 'redirect_uri=https://app.example.com/auth/callback' \
--data 'code_verifier='
```
```json title="Token response (example)"
{
"access_token": "",
"token_type": "Bearer",
"expires_in": 43199,
"refresh_token": "",
"id_token": ""
}
```
* `access_token` is the token you send to Copilot via API. It is a JSON Web Token. Send it as it is and do not build logic on its content.
* `expires_in` is the lifetime of the access token in seconds. Refresh the token before it expires.
* `id_token` is a JSON Web Token with the identity of the user. Use it for your own session, not for the API.
### Refresh the access token [#refresh-the-access-token]
```bash title="Refresh request"
curl --request POST \
--url https://iam.auth.haufe.io/oauth/v2/token \
--user ':' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token' \
--data 'refresh_token='
```
The response has the same shape as the token response. If the refresh fails, send the user through the login again.
## Call the API with the Access Token [#call-the-api-with-the-access-token]
Send the access token in the `Authorization` header. Do not send an `api-key` header.
```bash title="List available assistants"
curl --request GET \
--url https://api.haufe.ai/agents/v1/assistants \
--header 'Authorization: Bearer '
```
All endpoints in the [Quickstart](/docs/getting-started/quickstart) and the [API Reference](/api-reference) work the same way.
The examples there show the `api-key` header. Replace it with the `Authorization` header.
With OAuth user tokens, the content package of the user comes from the token. The request metadata `meta_data.user_data.licence` has no effect. Do not send it.
## Error Codes [#error-codes]
| HTTP Status | Response | Cause |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 401 | `{"message": "Unauthorized", "http_status_code": 401}` | The request has no `Authorization` header, the access token is expired or not valid, or your client has no active subscription. |
| 403 | `{"error_code": "assistant_not_licensed", "detail": "The access token has no licensed product for this assistant"}` | The user has no license for a product of this assistant. `GET /v1/assistants` lists only the assistants the user can use. |
| 422 | `{"error_code": "user_id_conflicts_with_token", "detail": "The user_id in the request differs from the user of the access token"}` | The request body names a `user_id` that is not the user of the token. Leave `user_id` out, the API fills it from the token. |
If you get a 401 with a token that worked before, refresh the token and retry once. If the refresh fails, send the user through the login again.
If every token of your client gets a 401, the subscription of your application is missing or not active. Contact your Haufe contact person.
## Next Steps [#next-steps]
# Overview
**Copilot via API** gives you access to a specialized AI agent through a simple API. You choose a **copilot** (e.g. Tax, HR) by providing an `assistant_id`, and then interact with it in one of two modes:
| Mode | Description |
| -------------------- | ------------------------------------------------------------------------------------- |
| **Threads** | Create a thread, exchange messages, and let the platform manage conversation history. |
| **Chat Completions** | Send a request, get a response. No server-side state. |
Both modes invoke the same underlying agent with the same capabilities. The only difference is how conversation state is managed.
## Choosing a copilot [#choosing-a-copilot]
Every request requires an `assistant_id` that determines which copilot handles your query. Each copilot is scoped to a specific domain and configured with the relevant tools and knowledge sources.
Your available copilots and their `assistant_id` values are provided during onboarding.
## Threads ([endpoints](/api-reference/threads/create_messages)) [#threads-endpoints]
Use this mode when you want to build a **multi-turn conversation** where context accumulates over time.
The platform stores the conversation history for you.
The workflow is a simple loop:
### 1. Create a thread [#1-create-a-thread]
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"assistant_id": "",
"user_id": "",
"title": "My conversation"
}'
```
```python
import requests
response = requests.post(
"https://api.haufe.ai/agents/v1/threads",
headers={"api-key": ""},
json={
"assistant_id": "",
"user_id": "",
"title": "My conversation",
},
)
thread_id = response.json()["id"]
```
```typescript
const response = await fetch("https://api.haufe.ai/agents/v1/threads", {
method: "POST",
headers: {
"content-type": "application/json",
"api-key": "",
},
body: JSON.stringify({
assistant_id: "",
user_id: "",
title: "My conversation",
}),
});
const { id: threadId } = await response.json();
```
### 2. Add a message [#2-add-a-message]
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads/:thread_id/messages \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"role": "user",
"content": "What are the deadlines for filing a tax return?"
}'
```
```python
response = requests.post(
f"https://api.haufe.ai/agents/v1/threads/{thread_id}/messages",
headers={"api-key": ""},
json={
"role": "user",
"content": "What are the deadlines for filing a tax return?",
},
)
```
```typescript
await fetch(
`https://api.haufe.ai/agents/v1/threads/${threadId}/messages`,
{
method: "POST",
headers: {
"content-type": "application/json",
"api-key": "",
},
body: JSON.stringify({
role: "user",
content: "What are the deadlines for filing a tax return?",
}),
}
);
```
### 3. Generate a response [#3-generate-a-response]
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads/:thread_id/run \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
```python
response = requests.post(
f"https://api.haufe.ai/agents/v1/threads/{thread_id}/run",
headers={"api-key": ""},
json={
"meta_data": {
"user_data": {
"licence": "",
}
}
},
)
answer = response.json()
```
```typescript
const response = await fetch(
`https://api.haufe.ai/agents/v1/threads/${threadId}/run`,
{
method: "POST",
headers: {
"content-type": "application/json",
"api-key": "",
},
body: JSON.stringify({
meta_data: {
user_data: {
licence: "",
},
},
}),
}
);
const answer = await response.json();
```
Repeat steps 2–3 to continue the conversation. The thread persists between requests, so each run has access to the full conversation history. The platform handles context truncation automatically when conversations grow long.
### Allowed Licenses [#allowed-licenses]
When calling `/run`, you must provide a valid license ID in the `meta_data.user_data.licence` field.
Your license ID is provided by your Haufe contact person.
Using an invalid or mismatching license ID may lead to degraded response quality but typically does not raise an error.
## Chat Completions ([endpoints](/api-reference/chat-completions/create_chat_completions_v1_chat_completions_post)) [#chat-completions-endpoints]
Use this mode when you need a **one-off answer** or want to integrate the copilot as a tool within your own application.
You provide the full list of messages in each request. Each message has a `role` (`user`, `system`, or `assistant`) and a `content` field. The API does not store anything between requests.
```bash
curl --request POST \
--url https://api.haufe.ai/agents/v1/chat/completions \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"assistant_id": "",
"messages": [
{
"role": "user",
"content": "What are the deadlines for filing a tax return?"
}
],
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
```python
import requests
response = requests.post(
"https://api.haufe.ai/agents/v1/chat/completions",
headers={"api-key": ""},
json={
"assistant_id": "",
"messages": [
{
"role": "user",
"content": "What are the deadlines for filing a tax return?",
}
],
"meta_data": {
"user_data": {
"licence": "",
}
},
},
)
answer = response.json()
```
```typescript
const response = await fetch(
"https://api.haufe.ai/agents/v1/chat/completions",
{
method: "POST",
headers: {
"content-type": "application/json",
"api-key": "",
},
body: JSON.stringify({
assistant_id: "",
messages: [
{
role: "user",
content: "What are the deadlines for filing a tax return?",
},
],
meta_data: {
user_data: {
licence: "",
},
},
}),
}
);
const answer = await response.json();
```
You can still have multi-turn conversations with chat completions — just include the full message history in every request. This gives you complete control over what context the copilot sees.
## Which mode should I use? [#which-mode-should-i-use]
* **Building a chat interface** where users have ongoing conversations? → **Threads**
* **Calling the copilot as a tool** from your own backend or workflow? → **Chat Completions**
* **Need full control** over what context is sent with each request? → **Chat Completions**
* **Don't want to manage conversation history** yourself? → **Threads**
## Next Steps [#next-steps]
# Rate Limits
Rate limits are enforced using two windows:
**RPS** (requests per second) controls how many concurrent requests you can send in a burst,
while **RPM** (requests per minute) controls your sustained throughput.
If you exceed either limit, the API returns HTTP `429` — see
[Handling Rate Limit Errors](#handling-rate-limit-errors) for retry guidance.
## Answer Generation Endpoints [#answer-generation-endpoints]
The following limits apply to answer-generation endpoints
(`/run(/stream)`, `/chat/completions(/stream)`) and to MCP `tools/call` requests on `/mcp`.
These share a single rate limit. Only they count toward your tier limits
— other API calls such as creating threads or listing messages are not affected.
MCP protocol traffic (`initialize`, `tools/list`, and the event stream) does **not** count
toward your tier limits; it falls under [Other Endpoints](#other-endpoints) below.
During the trial phase, the following limits apply:
| Tier | RPS | RPM |
| ---- | --- | --- |
| 0 | 15 | 60 |
Your current plan and its rate limits are visible in the [customer portal](https://portal.haufe.ai).
If you need higher limits or have any questions, contact your Haufe representative.
## OAuth Applications [#oauth-applications]
If your users authenticate with [OAuth user tokens](/docs/guides/oauth), a second limit applies to answer generation: a limit per end user.
One user cannot use up the budget of the other users of your application.
The limit of your plan applies to all users of your application together.
Both limits are listed with your plan in the [customer portal](https://portal.haufe.ai).
## Other Endpoints [#other-endpoints]
All other endpoints (e.g. listing assistants, fetching messages) share a single rate limit that applies regardless of your tier:
| RPS | RPM |
| --- | --- |
| 60 | 180 |
## Handling Rate Limit Errors [#handling-rate-limit-errors]
If you exceed these limits, the API returns HTTP `429 Too Many Requests`.
The response includes headers to help you implement retry logic — see [Error Handling](/docs/guides/error-handling#rate-limit-errors-http-429) for details.
Implement retry logic with exponential backoff where appropriate.
Feel free to reach out to your Haufe representative if you have any questions.
## Next Steps [#next-steps]
# Use Your Own Documents
You can upload files. The Copilot uses them as extra context when it generates answers.
This guide describes the full lifecycle of a file.
### Supported File Types [#supported-file-types]
| Type | MIME Type |
| ------------ | ------------------------------------------------------------------------- |
| PDF | `application/pdf` |
| Word (DOCX) | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| Excel (XLSX) | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| CSV | `text/csv` |
| Plain Text | `text/plain` |
Maximum file size: **10 MB**.
### Get a Signed Upload URL [#get-a-signed-upload-url]
Request a pre-signed URL to upload your file. The API returns a `file_id` and a `file_url`. Use the `file_url` to PUT the file content.
`GET https://api.haufe.ai/agents/v1/files/signed-url`
#### Query Parameters [#query-parameters]
| Parameter | Type | Required | Description |
| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `filename` | `string` | Yes | Name of the file including extension |
| `persist` | `boolean` | No | When `true` (default), the file is stored permanently. When `false`, the file is automatically deleted after 24 hours. |
```bash title="Get a signed upload URL"
curl --request GET \
--url "https://api.haufe.ai/agents/v1/files/signed-url?filename=report.pdf&persist=true" \
--header 'api-key: ' \
--header 'user-id: '
```
#### Response [#response]
```json
{
"file_url": "https://example-bucket.s3.amazonaws.com/example-file.txt",
"expires_in": 600,
"file_id": "123e4567-e89b-12d3-a456-426614174000",
"file_limits": {
"max_size": 10485760,
"allowed_types": [
"text/csv",
"text/plain",
"application/pdf",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
]
}
}
```
The signed URL expires after the time in `expires_in` (typically 600 seconds). If the upload does not
finish in time, request a new URL.
### Upload the File [#upload-the-file]
Use the returned `file_url` to upload the file content via a `PUT` request.
```bash title="Upload the file"
curl --request PUT \
--url "" \
--header 'Content-Type: application/pdf' \
--data-binary @report.pdf
```
Make sure the `Content-Type` header matches one of the `allowed_types` from the signed URL response.
A file with an unsupported type causes a processing error.
### Check Processing Status [#check-processing-status]
After the upload, the service processes the file asynchronously. Check the status to confirm the file is ready.
`GET https://api.haufe.ai/agents/v1/files/{file_id}/status`
```bash title="Check processing status"
curl --request GET \
--url "https://api.haufe.ai/agents/v1/files//status" \
--header 'api-key: ' \
--header 'user-id: '
```
#### Response [#response-1]
```json
{
"processing_status": "PROCESSED",
"warnings": {
"length": false,
"infected": false,
"empty": false
}
}
```
`processing_status` currently takes one of these values:
| `processing_status` | Meaning |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `PROCESSED` | Terminal. The file is ready to be referenced in a message |
| `FAILED` | Terminal. Processing did not succeed — see `processing_steps` and `validation_steps` for the cause |
| `PENDING_UPLOAD` | In progress. The upload has not been completed yet |
| `PROCESSING` | In progress. Text extraction is running |
| `ANTIVIRUS_SCANNING` | In progress. The file is being scanned |
Poll this endpoint until `processing_status` is `PROCESSED` or `FAILED`. Do this before you reference
the file in a message. Treat every other value as "not finished yet". Do not branch on the individual
in-progress states — they are short-lived, and the list above can grow without notice.
On `FAILED`, read the `processing_steps` and `validation_steps` arrays to find the cause.
On `PROCESSED`, also check the `warnings` object. The service rejects a file with `empty: true` or
`length: true` when you attach it to a message. See
[Message Validation](/docs/validation/messages#attachment-rules) for the error codes.
### Verify the Upload [#verify-the-upload]
#### List All Files [#list-all-files]
Retrieve a paginated list of all persisted files for your user. This list includes only files uploaded with `persist=true`. Temporary files (`persist=false`) do not appear.
`GET https://api.haufe.ai/agents/v1/files`
#### Query Parameters [#query-parameters-1]
| Parameter | Type | Required | Description |
| --------- | --------- | -------- | -------------------------------------------------- |
| `page` | `integer` | No | Page number (1-based). Defaults to `1` |
| `limit` | `integer` | No | Number of files per page (1–100). Defaults to `30` |
```bash title="List all files"
curl --request GET \
--url "https://api.haufe.ai/agents/v1/files?page=1&limit=30" \
--header 'api-key: ' \
--header 'user-id: '
```
##### Response [#response-2]
```json
{
"files": [
{
"file_id": "9c3e00fe-1b42-413a-bf44-39ad9491ad86",
"file_name": "report.pdf"
},
{
"file_id": "cbfe557e-144e-43f3-823f-d72be00084a2",
"file_name": "expenses.xlsx"
}
],
"page": 1,
"limit": 30,
"total": 2
}
```
#### Retrieve File Content [#retrieve-file-content]
Fetch the extracted text of a file to confirm the service processed it correctly.
`GET https://api.haufe.ai/agents/v1/files/{file_id}`
```bash title="Retrieve file content"
curl --request GET \
--url "https://api.haufe.ai/agents/v1/files/" \
--header 'api-key: ' \
--header 'user-id: '
```
The endpoint returns the extracted text of the file as a plain string.
### Use with Chat Completions [#use-with-chat-completions]
After the service processes a file, you can reference it in a single stateless request.
Add the file as an `attachments` entry on a `user` message:
The top-level `user_id` **must** match the `user-id` header you used during file upload.
Do **not** set `user_id` on the attachment itself. At most **3 attachments** per message are allowed.
```bash title="Chat completions with attachment"
curl --request POST \
--url https://api.haufe.ai/agents/v1/chat/completions \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"assistant_id": "",
"user_id": "",
"messages": [
{
"role": "user",
"content": "Summarize the attached report.",
"attachments": [
{
"file_id": ""
}
]
}
],
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
### Use with Threads [#use-with-threads]
For conversational workflows, create a thread, post a message with the attachment, and run the thread to get a response.
The `user_id` on the thread **must** match the `user-id` header you used during file upload.
Do **not** set `user_id` on the attachment itself. At most **3 attachments** per message are allowed.
**1. Create a thread:**
```bash title="Create a thread with user_id"
curl --request POST \
--url https://api.haufe.ai/agents/v1/threads \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"assistant_id": "",
"user_id": ""
}'
```
**2. Post a message** with the attachment:
```bash title="Thread message with attachment"
curl --request POST \
--url "https://api.haufe.ai/agents/v1/threads//messages" \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"role": "user",
"content": "Summarize the attached report.",
"attachments": [
{
"file_id": ""
}
]
}'
```
**3. Run the thread:**
```bash title="Run the thread"
curl --request POST \
--url "https://api.haufe.ai/agents/v1/threads//run" \
--header 'content-type: application/json' \
--header 'api-key: ' \
--data '{
"meta_data": {
"user_data": {
"licence": ""
}
}
}'
```
### Check Which Attachments Were Used [#check-which-attachments-were-used]
The service loads the file content when it generates the answer, not when you attach the file.
So the assistant message reports, per file, whether its content reached the answer. This is in
`meta_data.attachments`:
```json
{
"role": "assistant",
"content": "The report covers ...",
"meta_data": {
"attachments": [
{ "file_id": "", "file_name": "report.pdf", "status": "ok" },
{ "file_id": "", "file_name": "notes.txt", "status": "not_found" }
]
}
}
```
| Field | Meaning |
| ----------- | ----------------------------------------------------------------------- |
| `file_id` | The `file_id` you attached to the message |
| `file_name` | Original name of the file, or `null` when it is unknown to the service |
| `status` | Whether the content was loaded and considered for the answer, see below |
| `status` | Meaning |
| ----------- | --------------------------------------------------------------------------------------------- |
| `ok` | The content was loaded and considered for the answer |
| `not_found` | The file no longer exists on the storage service and was therefore **not** considered |
| `error` | The file exists but could not be loaded, e.g. the storage service was temporarily unreachable |
| `empty` | The file exists but no text could be extracted from it |
`error` and `empty` do **not** mean the file is gone. The file is still there, but its content
could not be used for this answer.
A file that you deleted via `DELETE /files/{file_id}` does not appear in the list. The service
skips it on purpose and does not report it as a failure.
In streaming mode this data arrives in a separate chunk with an empty `content`.
Like the rest of `meta_data`, this field is part of the assistant response schema. Use
`GET /assistants/{assistant_id}` to check whether your assistant returns it.
### Delete a File [#delete-a-file]
Remove a file that you no longer need. After deletion, you cannot reference the file in new messages. The service also stops using it for response generation in threads that contained it.
`DELETE https://api.haufe.ai/agents/v1/files/{file_id}`
```bash title="Delete a file"
curl --request DELETE \
--url "https://api.haufe.ai/agents/v1/files/" \
--header 'api-key: ' \
--header 'user-id: '
```
Returns `204 No Content` on success with an empty response body.
## Next Steps [#next-steps]
# Overview
The Copilot API validates incoming requests before processing them. Invalid payloads are rejected with HTTP `422 Unprocessable Entity`.
Validation is applied at two levels:
# Message Validation
The following rules are enforced on message stacks:
Either directly provided via `/chat/completions` or built server-side by attaching messages to a thread.
All violations return an HTTP `422 Unprocessable Entity`.
## Content Rules [#content-rules]
These rules apply to the `content` field of every message type.
| Rule | Details |
| -------------- | ------------------------------------------------------------------------------------------------- |
| Non-empty | `content` must not be blank or whitespace-only (applies to `user`, `system`, and `tool` messages) |
| Maximum length | `content` must not exceed **30,000 characters** |
| Valid Unicode | `content` must be valid UTF-8; broken Unicode characters are rejected |
### Assistant message content [#assistant-message-content]
`assistant` messages follow a slightly different rule:
* `content` must be non-empty **when `tool_calls` is absent**.
* `content` must be **empty** when `tool_calls` is present.
## Message List Rules [#message-list-rules]
| Rule | Details |
| -------------------------- | -------------------------------------------------------------------- |
| Non-empty list | The `messages` array must contain at least one message |
| Last message | The last message must have role `user` or `tool` |
| System message uniqueness | At most **one** `system` message is allowed |
| Assistant message ordering | An `assistant` message must be directly preceded by a `user` message |
#### Example — valid message stack [#example--valid-message-stack]
```json
[
{ "role": "system", "content": "You are a helpful HR expert." },
{ "role": "user", "content": "What is BEM?" },
{ "role": "assistant", "content": "BEM stands for ...", "sources": [] },
{ "role": "user", "content": "Can you elaborate?" }
]
```
#### Example — invalid: assistant without preceding user message [#example--invalid-assistant-without-preceding-user-message]
```json
[
{ "role": "system", "content": "You are a helpful HR expert." },
{ "role": "assistant", "content": "BEM stands for ...", "sources": [] }
]
```
## Attachment Rules [#attachment-rules]
Attachments can be added to `user` messages via the `attachments` field.
**Recommended flow:** upload the file through the `/files` endpoints, set `user_id`
either on the thread (`POST /threads`) or on the chat-completions request body
(`POST /chat/completions`), and reference the file by its `file_id` only — leave
`AttachmentCreate.user_id` and `AttachmentCreate.base_url` empty.
| Rule | Details |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum attachments | **3 attachments** per `user` message. More are rejected with HTTP `422` and error code `user_message_too_many_attachments`. |
| Uniqueness within a message | The same attachment must not be listed twice on one `user` message. Rejected with HTTP `422` and error code `user_message_not_unique_attachments`. |
| Global uniqueness | Each attachment is identified by its `file_id`, `user_id`, and `base_url`. The same attachment must not appear more than once across all messages in a single request. Rejected with HTTP `422` and error code `attachment_not_unique`. |
| `user_id` optional, do not set | Should be left empty. Provide the `user_id` once on the thread (`POST /threads`) or on the chat-completions request body (`POST /chat/completions`). The `AttachmentCreate.user_id` override is intended for internal usage only. |
| `base_url` optional, do not set | Defaults to the production file storage URL. The `AttachmentCreate.base_url` override is intended for internal usage only — e.g. when referencing a file on a non-production environment. A URL outside the allowed set is rejected with HTTP `422` and error code `attachment_url_invalid`. |
| User ID must be resolvable | If a message carries an attachment, a `user_id` must be available somewhere — on the thread, on the request body, or (for internal use) on the attachment itself. If none is set the request is rejected with HTTP `422` and error code `attachment_requires_user_id`. |
| File must exist | The `file_id` must exist on the file storage service for the resolved `user_id`. Unknown or already deleted files are rejected with HTTP `404` and error code `attachment_document_does_not_exist`. |
| File must be accessible | If the resolved `user_id` is not allowed to read the file, the request is rejected with HTTP `403` and error code `attachment_access_forbidden`. |
| File must be processed | The file must have reached **PROCESSED** state on the file storage service before it can be attached. Files that are not finished yet — still uploading, being scanned, or still being processed — return HTTP `409` with error code `attachment_document_still_processing`; retry once processing completed. Files that finished in any other state return HTTP `400` with error code `attachment_document_raised_an_error`. |
| File must be clean | A file the storage service flagged as infected is rejected with HTTP `409` and error code `conflict`. |
| File must contain text | If no text could be extracted from the file (`warnings.empty` on `GET /files/{file_id}/status`), the request is rejected with HTTP `422` and error code `attachment_is_below_minimum_size`. There is no minimum length beyond that. |
| Extracted text must fit the limit | The extracted text must not exceed **60,000 characters**, measured on the whole document. Longer documents are rejected with HTTP `422` and error code `attachment_exceeds_max_size`. Split large documents into several files. |
| Non-persisted files expire | Files uploaded with `persist=false` (via `GET /files/signed-url`) are only retained for **24 hours**. After that they cannot be used for answer generation. Use `persist=true` (the default) for files that should remain available longer. |
These checks run when the attachment is added to a message. The file content itself is only loaded
when an answer is generated, so a file that was deleted in the meantime does not fail the request —
it is reported back in `meta_data.attachments` instead. See
[Uploading Files](/docs/guides/uploading-files).
Validating an attachment requires calls to the file storage service. If that service is
unreachable, the request fails with HTTP `502` and error code `attachment_document_not_reachable`.
Unlike the rules above this is transient and not caused by your request — retry it.
## Tool Message Rules [#tool-message-rules]
Tool messages (`role: "tool"`) return tool call results to the assistant.
| Rule | Details |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Must follow an assistant message | A `tool` message must be preceded by an `assistant` message that requested the corresponding tool call |
| All requested tool calls must be answered | If an `assistant` message requests multiple tool calls, all corresponding `tool` messages must immediately follow it |
| Unique `tool_call_id` | Each `tool_call_id` must be unique across the entire `messages` array |
| Optional `status` | `"success"` or `"error"`. Defaults to `"success"` |
#### Example — valid tool message sequence [#example--valid-tool-message-sequence]
```json
[
{ "role": "user", "content": "Search for BEM regulations." },
{ "role": "assistant", "content": "", "sources": [], "tool_calls": [
{ "id": "call_1", "type": "function", "function": { "name": "search", "arguments": "{}" } },
{ "id": "call_2", "type": "function", "function": { "name": "fetch", "arguments": "{}" } }
]},
{ "role": "tool", "content": "Search result...", "tool_call_id": "call_1" },
{ "role": "tool", "content": "Fetch result...", "tool_call_id": "call_2" }
]
```
#### Example — invalid: missing tool message for `call_2` [#example--invalid-missing-tool-message-for-call_2]
```json
[
{ "role": "user", "content": "Search for BEM regulations." },
{ "role": "assistant", "content": "", "sources": [], "tool_calls": [
{ "id": "call_1", "type": "function", "function": { "name": "search", "arguments": "{}" } },
{ "id": "call_2", "type": "function", "function": { "name": "fetch", "arguments": "{}" } }
]},
{ "role": "tool", "content": "Search result...", "tool_call_id": "call_1" }
]
```
## Tool Choice Rules [#tool-choice-rules]
When using the `tools` and `tool_choice` fields on the request:
| Rule | Details |
| ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `tool_choice` requires `tools` | `tool_choice` cannot be set if `tools` is absent or empty |
| Named tool choice must be valid | If `tool_choice` specifies a function by name, that function must be present in the `tools` list |
**Defaults:**
* If `tools` is provided but `tool_choice` is omitted, it defaults to `"auto"`.
* If neither is provided, `tool_choice` defaults to `"none"`.
# Request Metadata Validation
The `meta_data` field in a Chat Completions or Threads-Run request carries optional context about the end user
(e.g. licence, preferences). Which fields inside `meta_data` are **required** depends on the
copilot's configuration.
## Structure [#structure]
The top-level `meta_data` object currently supports the following structure:
```json
{
"meta_data": {
"user_data": {
"licence": ""
}
}
}
```
All fields default to `null` and are optional unless the Copilot requires them.
## Copilot-Specific Required Fields [#copilot-specific-required-fields]
Each Copilot can require different fields. If a required field is missing, `null` or an empty string, the API
returns HTTP `400 Bad Request`. Look up the required fields via `GET /v1/assistants/{assistant_id}`.
With an OAuth user access token, `user_data.licence` comes from the token. `GET /v1/assistants/{assistant_id}` then
lists only the fields you must send, and the API drops a `licence` value you send. See the [OAuth guide](/docs/guides/oauth).
### Example — request with required `user_data` [#example--request-with-required-user_data]
If the Copilot requires `user_data.licence`, the following request is valid:
```json
{
"assistant_id": "00000000-0000-0000-0000-000000000200",
"messages": [{ "role": "user", "content": "What is BEM?" }],
"meta_data": {
"user_data": {
"licence": "PI123"
}
}
}
```
### Example — request missing a required field [#example--request-missing-a-required-field]
If `user_data` is required but omitted, the API returns `400`:
```json
{
"error_code": "request_metadata_missing_or_incomplete",
"detail": "Request lacks required request metadata"
}
```
# API Reference
## Copilot via API [#copilot-via-api]
This API lets you integrate Haufe.ai copilot capabilities directly into your applications.
Build stateful conversation threads or make stateless chat completions calls to create AI-powered user experiences.
### Authentication [#authentication]
All API requests require one credential. Send the header that matches your authentication method.
API key:
```bash
api-key: ${YOUR_API_KEY}
```
OAuth user token (your users log in with their Haufe account):
```bash
Authorization: Bearer ${ACCESS_TOKEN}
```
See [Authentication](/docs/getting-started/authentication) and [OAuth: Let Your Users Log In with Haufe](/docs/guides/oauth).
### Endpoints by Category [#endpoints-by-category]
### Getting Help [#getting-help]
* Visit the [Documentation](/docs) for integration guides and tutorials.
* Return to the [Overview](/) for platform information.
# List assistants
```json
{
"method": "GET",
"path": "/v1/assistants",
"tags": [
"Assistants"
],
"summary": "List assistants",
"description": "Returns all assistants available for the authenticated tenant. With a user access token, only the assistants licensed to the user are returned.",
"operationId": "get_all_assistants_v1_assistants_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/Assistant"
},
"type": "array",
"title": "Response Get All Assistants V1 Assistants Get"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"error_code": {
"type": "string",
"title": "Error Code"
},
"detail": {
"type": "string",
"title": "Detail"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"type": "object",
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"description": "Schema of the ServiceExceptions"
}
]
},
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"message": {
"type": "string",
"title": "Message"
}
},
"type": "object",
"required": [
"message"
],
"title": "GraviteeExceptionSchema"
}
]
},
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"error_code": {
"type": "string",
"title": "Error Code"
},
"detail": {
"type": "string",
"title": "Detail"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"type": "object",
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"description": "Schema of the ServiceExceptions"
}
]
},
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
}
}
}
}
},
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"schemas": {
"Assistant": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "assistant's identifier"
},
"name": {
"type": "string",
"title": "Name",
"description": "assistant's descriptive name"
},
"request_required_fields": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Request Required Fields"
},
"streaming": {
"type": "boolean",
"title": "Streaming",
"description": "if assistant can stream"
},
"meta_data_response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data Response Schema",
"description": "Metadata schema for the assistant response"
}
},
"type": "object",
"required": [
"id",
"name",
"request_required_fields",
"streaming",
"meta_data_response_schema"
],
"title": "Assistant",
"examples": [
{
"id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"meta_data_response_schema": {
"properties": {
"type": {
"const": "lgagentmetadatamodel",
"default": "lgagentmetadatamodel",
"enum": [
"53aa66b7-b874-407f-967c-3a959c919d62"
],
"title": "Type",
"type": "string"
},
"legal_advice": {
"description": "Indicates if the user query is a legal advice.",
"title": "Is Legal Advice",
"type": "boolean"
},
"intent": {
"description": "Intent of the user query.",
"title": "Intent",
"type": "string"
}
},
"required": [
"legal_advice",
"intent"
],
"title": "LgAgentMetaDataModel",
"type": "object"
},
"name": "Haufe Copilot Tax",
"request_required_fields": {
"__root__": [
"user_data"
],
"user_data": [
"licence"
]
},
"streaming": true
},
{
"id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
"name": "Haufe Copilot HR",
"streaming": true
}
]
}
}
}
```
# Get an assistant
```json
{
"method": "GET",
"path": "/v1/assistants/{assistant_id}",
"tags": [
"Assistants"
],
"summary": "Get an assistant",
"description": "Returns the properties of a single assistant by ID. With a user access token, `request_required_fields` lists only the fields the client must send.",
"operationId": "get_assistant_properties_v1_assistants__assistant_id__get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "assistant_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Assistant Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Assistant"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"validation_error": {
"summary": "Assistant id missing",
"value": {
"error_code": "validation_error",
"detail": [
{
"loc": [
"body",
"assistant_id"
],
"message": "Field required",
"type": "missing"
}
]
},
"schema": {
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Detail",
"type": "array"
}
},
"required": [
"error_code",
"detail"
],
"title": "CustomRequestValidationErrorSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Detail",
"type": "array"
}
},
"required": [
"error_code",
"detail"
],
"title": "CustomRequestValidationErrorSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"Assistant": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id",
"description": "assistant's identifier"
},
"name": {
"type": "string",
"title": "Name",
"description": "assistant's descriptive name"
},
"request_required_fields": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Request Required Fields"
},
"streaming": {
"type": "boolean",
"title": "Streaming",
"description": "if assistant can stream"
},
"meta_data_response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data Response Schema",
"description": "Metadata schema for the assistant response"
}
},
"type": "object",
"required": [
"id",
"name",
"request_required_fields",
"streaming",
"meta_data_response_schema"
],
"title": "Assistant",
"examples": [
{
"id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"meta_data_response_schema": {
"properties": {
"type": {
"const": "lgagentmetadatamodel",
"default": "lgagentmetadatamodel",
"enum": [
"53aa66b7-b874-407f-967c-3a959c919d62"
],
"title": "Type",
"type": "string"
},
"legal_advice": {
"description": "Indicates if the user query is a legal advice.",
"title": "Is Legal Advice",
"type": "boolean"
},
"intent": {
"description": "Intent of the user query.",
"title": "Intent",
"type": "string"
}
},
"required": [
"legal_advice",
"intent"
],
"title": "LgAgentMetaDataModel",
"type": "object"
},
"name": "Haufe Copilot Tax",
"request_required_fields": {
"__root__": [
"user_data"
],
"user_data": [
"licence"
]
},
"streaming": true
},
{
"id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
"name": "Haufe Copilot HR",
"streaming": true
}
]
}
}
}
```
# Stream a chat completion with content blocks
```json
{
"method": "POST",
"path": "/v1/chat/completions/events/stream",
"tags": [
"Chat Completions"
],
"summary": "Stream a chat completion with content blocks",
"description": "Streams an assistant response as NDJSON with a list of content blocks.",
"operationId": "create_chat_completions_events_stream_v1_chat_completions_events_stream_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionsCreateNew"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageEventsChunkResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"incorrect_stack_ending": {
"summary": "Incorrect Stack Ending",
"value": {
"error_code": "incorrect_stack_ending",
"detail": "The last message in the stack must be a user, tool, or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_stack_start": {
"summary": "Invalid Stack Start",
"value": {
"error_code": "invalid_stack_start",
"detail": "A message stack must start with a user or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"system_message_is_not_unique": {
"summary": "System Message Is Not Unique",
"value": {
"error_code": "system_message_is_not_unique",
"detail": "A thread can only contain one system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_is_not_unique": {
"summary": "Tool Message Is Not Unique",
"value": {
"error_code": "tool_message_is_not_unique",
"detail": "Tool message is not unique in the thread. There is a ToolMessage with the same id."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_message_must_follow_assistant_message": {
"summary": "User Message Must Follow Assistant Message",
"value": {
"error_code": "user_message_must_follow_assistant_message",
"detail": "A user message is expected after an assistant message without tool calls."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_message_follows_user_message": {
"summary": "Invalid Message Follows User Message",
"value": {
"error_code": "invalid_message_follows_user_message",
"detail": "Only an assistant or user message may follow a user message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_must_follow_assistant_message": {
"summary": "Tool Message Must Follow Assistant Message",
"value": {
"error_code": "tool_message_must_follow_assistant_message",
"detail": "Tool messages can only be posted after an assistant message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_has_no_matching_tool_call": {
"summary": "Tool Message Has No Matching Tool Call",
"value": {
"error_code": "tool_message_has_no_matching_tool_call",
"detail": "Tool message id not found in an preceding assistant message's tool calls in the thread"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_does_not_contain_all_tool_calls": {
"summary": "Thread Does Not Contain All Tool Calls",
"value": {
"error_code": "thread_does_not_contain_all_tool_calls",
"detail": "Thread does not contain all requested tool calls"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_empty": {
"summary": "Thread Empty",
"value": {
"error_code": "thread_empty",
"detail": "The thread is empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_last_message_invalid": {
"summary": "Thread Last Message Invalid",
"value": {
"error_code": "thread_last_message_invalid",
"detail": "Last message in the thread has to be a user, system or tool message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"content_filter_error": {
"summary": "Content Filter Error",
"value": {
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_id_conflicts_with_token": {
"summary": "User Id Conflicts With Token",
"value": {
"error_code": "user_id_conflicts_with_token",
"detail": "The user_id in the request differs from the user of the access token"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"engine_does_not_support_streaming": {
"summary": "Engine Does Not Support Streaming",
"value": {
"error_code": "engine_does_not_support_streaming",
"detail": "The selected engine does not support streaming responses. Please use the non-streaming endpoint."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_persistence_mismatch": {
"summary": "Attachment Persistence Mismatch",
"value": {
"error_code": "attachment_persistence_mismatch",
"detail": "The attachment could not be stored due to an internal error."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"examples": {
"internal_service_error": {
"summary": "Internal Service Error",
"value": {
"error_code": "internal_service_error",
"detail": "An internal service required for processing the request is currently unavailable. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ChatCompletionsCreateNew": {
"properties": {
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id",
"description": "The ID of the assistant to invoke."
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id",
"description": "Optional end-user ID for tracking."
},
"messages": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/HumanMessageCreate"
},
{
"$ref": "#/components/schemas/SystemMessageCreate"
},
{
"$ref": "#/components/schemas/ToolMessageCreate"
},
{
"$ref": "#/components/schemas/AssistantMessageCreate"
}
],
"discriminator": {
"propertyName": "role",
"mapping": {
"assistant": "#/components/schemas/AssistantMessageCreate",
"system": "#/components/schemas/SystemMessageCreate",
"tool": "#/components/schemas/ToolMessageCreate",
"user": "#/components/schemas/HumanMessageCreate"
}
}
},
"type": "array",
"title": "Messages",
"description": "Array of messages forming the conversation context. Must contain at least one user message. The last message must be a user or tool message. At most one system message allowed. An assistant message must be preceded by a user message. An assistant message requesting tool calls must be immediately followed by the corresponding tool messages. For every tool message, a corresponding assistant message with the same tool_call_id must exist."
},
"meta_data": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestMetaData"
},
{
"type": "null"
}
],
"description": "Optional request metadata."
},
"tools": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCallParam"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "Tool definitions the assistant may call. If provided, tool_choice defaults to auto."
},
"tool_choice": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"auto",
"required"
]
},
{
"$ref": "#/components/schemas/MessageNamedToolChoiceParam"
},
{
"type": "null"
}
],
"title": "Tool Choice",
"description": "Controls which tool the model calls. Options: none, auto, or a named tool. Requires tools to be set."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"assistant_id",
"messages"
],
"title": "ChatCompletionsCreateNew",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"messages": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
}
],
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"messages": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt sowohl für den Arbeitgeber als auch für den Arbeitnehmer.",
"role": "assistant",
"sources": []
},
{
"content": "Kann die Probezeit verlängert werden?",
"role": "user"
}
],
"meta_data": {
"user_data": {
"licence": "PI123"
}
},
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
}
]
},
"MessageEventsChunkResponse": {
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"title": "Message Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"delta": {
"$ref": "#/components/schemas/AssistantMessageEventsDeltaRead"
}
},
"type": "object",
"required": [
"message_id",
"thread_id",
"created_at",
"delta"
],
"title": "MessageEventsChunkResponse",
"description": "Streaming chunk yielded by POST /v1/threads/{thread_id}/run/events/stream.\n\nThe content-block counterpart to MessageChunkResponse: delta.content_blocks is list[ContentBlock]\ninstead of str.",
"examples": [
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content_blocks": [
{
"reasoning": "The user is asking about notice periods during probation.",
"type": "reasoning"
}
],
"role": "assistant",
"sources": []
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content_blocks": [
{
"text": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen.",
"type": "text"
}
],
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit...",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"HumanMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "user",
"title": "Role",
"default": "user"
},
"content": {
"type": "string",
"title": "Content",
"description": "The message text. Must be valid Unicode and non-empty. Maximum length: 30000 characters."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentCreate"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Optional file attachments. Maximum 3 attachment(s), each must be unique by file_id/user_id/base_url."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "HumanMessageCreate",
"examples": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"attachments": [
{
"file_id": "c3d4e5f6-7890-abcd-ef01-345678901234",
"user_id": "user_123"
}
],
"content": "Fasse den mitgeschickten Inhalt zusammen.",
"role": "user"
}
]
},
"SystemMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "system",
"title": "Role",
"default": "system"
},
"content": {
"type": "string",
"title": "Content",
"description": "System instructions for the assistant. Must be non-empty. Maximum length: 30000 characters."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "SystemMessageCreate",
"examples": [
{
"content": "Du bist ein Experte für deutsches Arbeitsrecht. Antworte stets auf Deutsch und verweise auf relevante Gesetzesgrundlagen.",
"role": "system"
}
]
},
"ToolMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "tool",
"title": "Role",
"default": "tool"
},
"content": {
"type": "string",
"title": "Content",
"description": "The tool execution result. Must be non-empty. Maximum length: 30000 characters."
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id",
"description": "The ID of the tool call this message responds to. Must match a tool_call_id from the preceding assistant message."
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"description": "The state of the tool run. Send \"error\" when the tool failed. Defaults to \"success\".",
"default": "success"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"tool_call_id"
],
"title": "ToolMessageCreate",
"examples": [
{
"content": "{\"results\": [{\"title\": \"§ 622 BGB Kündigungsfristen\", \"snippet\": \"Während einer vereinbarten Probezeit kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.\"}]}",
"role": "tool",
"status": "success",
"tool_call_id": "call_abc123"
}
]
},
"AssistantMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content",
"description": "The assistant response text. Maximum length: 30000 characters. Must be non-empty when tool_calls is absent. Must be empty if tool_calls is present."
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceCreate"
},
"type": "array",
"title": "Sources",
"description": "List of sources used as context for message generation"
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls",
"description": "The tool calls generated by the model, such as function calls."
},
"meta_data": {
"anyOf": [
{
"oneOf": [
{
"$ref": "#/components/schemas/LgAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/HRAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/CommonMetaDataModel"
},
{
"$ref": "#/components/schemas/DeepAgentMetaDataModel"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"53aa66b7-b874-407f-967c-3a959c919d62": "#/components/schemas/LgAgentMetaDataModel",
"689fa139-f46e-45e3-89a4-67efcde73114": "#/components/schemas/HRAgentMetaDataModel",
"6c1f6752-93e8-4b73-a946-2391f3dae805": "#/components/schemas/CommonMetaDataModel",
"f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f": "#/components/schemas/DeepAgentMetaDataModel"
}
}
},
{
"type": "null"
}
],
"title": "Meta Data",
"description": "Additional meta data for the assistant message. The meta_data response schema is dependent on the assistant.The schema is included in the assistant properties and can be retrieved via GET /assistants/{assistant_id}."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"sources"
],
"title": "AssistantMessageCreate",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten – sowohl Arbeitgeber als auch Arbeitnehmer können mit einer Frist von zwei Wochen kündigen.",
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
{
"content": "",
"role": "assistant",
"sources": [],
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"RequestMetaData": {
"properties": {
"user_data": {
"anyOf": [
{
"$ref": "#/components/schemas/UserData"
},
{
"type": "null"
}
]
}
},
"type": "object",
"title": "RequestMetaData"
},
"MessageToolCallParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageToolCallParam"
},
"MessageNamedToolChoiceParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionParam"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageNamedToolChoiceParam"
},
"AssistantMessageEventsDeltaRead": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content_blocks": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TextContentBlock"
},
{
"$ref": "#/components/schemas/ReasoningContentBlock"
},
{
"$ref": "#/components/schemas/ToolCall"
},
{
"$ref": "#/components/schemas/ToolResult"
},
{
"$ref": "#/components/schemas/ServerToolCall"
},
{
"$ref": "#/components/schemas/ServerToolResult"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"reasoning": "#/components/schemas/ReasoningContentBlock",
"server_tool_call": "#/components/schemas/ServerToolCall",
"server_tool_result": "#/components/schemas/ServerToolResult",
"text": "#/components/schemas/TextContentBlock",
"tool_call": "#/components/schemas/ToolCall",
"tool_result": "#/components/schemas/ToolResult"
}
}
},
"type": "array",
"title": "Content Blocks"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
}
},
"type": "object",
"required": [
"content_blocks",
"sources"
],
"title": "AssistantMessageEventsDeltaRead",
"description": "Streaming delta for events streaming where content is a list[ContentBlock]."
},
"AttachmentCreate": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"base_url": {
"type": "string",
"title": "Base Url",
"default": "https://api.files.haufe.io"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "AttachmentCreate"
},
"SourceCreate": {
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Identifier of the source object."
},
"content": {
"type": "string",
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"meta_data"
],
"title": "SourceCreate"
},
"MessageToolCall": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"function": {
"$ref": "#/components/schemas/Function"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"id",
"function",
"type"
],
"title": "MessageToolCall",
"description": "Structure of the tool call in the assistant message.\nThis corresponds to the LLM requesting to execute a tool."
},
"LgAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "53aa66b7-b874-407f-967c-3a959c919d62",
"title": "Type",
"default": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "Intent of the user query."
},
"legal_advice": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Legal Advice",
"description": "Indicates if the user query is a legal advice."
},
"rephrased_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rephrased Query",
"description": "Rephrased query if it was detected as legal advice."
},
"tool_call_info": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Call Info",
"description": "Information about the tool calls, such as function calls, parameters and results."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentMetaInfo"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments of the run as loaded by the engine, one entry per file with its load status."
}
},
"type": "object",
"required": [
"intent"
],
"title": "LgAgentMetaDataModel"
},
"HRAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "689fa139-f46e-45e3-89a4-67efcde73114",
"title": "Type",
"default": "689fa139-f46e-45e3-89a4-67efcde73114"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "The intent of the user query"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
}
},
"type": "object",
"required": [
"intent",
"finish_reason"
],
"title": "HRAgentMetaDataModel"
},
"CommonMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "6c1f6752-93e8-4b73-a946-2391f3dae805",
"title": "Type",
"default": "6c1f6752-93e8-4b73-a946-2391f3dae805"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detail",
"description": "Detail information about the error"
}
},
"type": "object",
"required": [
"finish_reason",
"detail"
],
"title": "CommonMetaDataModel"
},
"DeepAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f",
"title": "Type",
"default": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f"
},
"token_usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage information for the assistant message"
}
},
"type": "object",
"required": [
"token_usage"
],
"title": "DeepAgentMetaDataModel"
},
"UserData": {
"properties": {
"licence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Licence"
}
},
"type": "object",
"title": "UserData"
},
"FunctionDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"parameters": {
"additionalProperties": true,
"type": "object",
"title": "Parameters"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
}
},
"type": "object",
"required": [
"name",
"parameters"
],
"title": "FunctionDefinition"
},
"FunctionParam": {
"properties": {
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "FunctionParam"
},
"TextContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "text",
"title": "Type",
"default": "text"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"annotations": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Annotations"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"text"
],
"title": "TextContentBlock",
"description": "Text output. Attributes mirror LangChain's ``TextContentBlock`` (core 1.4.x).\n\nLangChain marks every field except ``text`` as ``NotRequired``, so here they are optional with a\n``None`` default. ``annotations`` stays a loose ``list[dict]`` instead of a copy of LangChain's\n``Annotation`` union, because HAI does not process citations."
},
"ReasoningContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "reasoning",
"title": "Type",
"default": "reasoning"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"title": "ReasoningContentBlock",
"description": "Reasoning output. Mirrors LangChain's ``ReasoningContentBlock`` (core 1.4.x)."
},
"ToolCall": {
"properties": {
"type": {
"type": "string",
"const": "tool_call",
"title": "Type",
"default": "tool_call"
},
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"args": {
"additionalProperties": true,
"type": "object",
"title": "Args"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"name",
"args"
],
"title": "ToolCall",
"description": "Client-side tool call request."
},
"ToolResult": {
"properties": {
"type": {
"type": "string",
"const": "tool_result",
"title": "Type",
"default": "tool_result"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id"
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"default": "success"
},
"output": {
"type": "string",
"title": "Output",
"default": ""
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"tool_call_id"
],
"title": "ToolResult",
"description": "Result of a *client-side* tool call, carried in the ``content_blocks`` of a ``ToolMessage``.\n\nThe caller supplies this block, so a model never emits one.\nLangChain has no client-side tool-result block for that reason: there the result is the ``ToolMessage`` itself.\nHAI needs one because every message role stores its payload as content blocks, and the link to the request\n(``tool_call_id``) needs a carrier.\n\n``output`` is the tool output. It is a ``str`` because a ``str`` is what the API\nreceives, what the model sees, and what the v1 API returns.\n\nIt often holds a JSON-serialized object, which this block does not parse\nParsing also lost data (duplicate keys, escaping, whitespace) and let ``json.loads`` admit ``NaN`` into a\nJSONB-bound column.\n\nA consumer that wants the structure back parses it once it knows which tool produced the output.\n``ServerToolResult.output`` keeps its structure, because there LangChain gives it to us.\n\n``status`` mirrors LangChain's ``ToolMessage.status``: two values, defaulting to ``\"success\"``.\nLangChain keeps it on the message because the message *is* the result there. HAI keeps it on the\nblock, so a tool result carries its own outcome wherever the block travels. The message-level\ncounterpart is ``ToolMessage.status``, which reads it back off this block."
},
"ServerToolCall": {
"properties": {
"type": {
"type": "string",
"const": "server_tool_call",
"title": "Type",
"default": "server_tool_call"
},
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"args": {
"additionalProperties": true,
"type": "object",
"title": "Args"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"name",
"args"
],
"title": "ServerToolCall",
"description": "Server-side / inline tool call executed by the agent within the same turn (e.g. DeepAgent).\n\nMirrors LangChain's ``ServerToolCall``."
},
"ServerToolResult": {
"properties": {
"type": {
"type": "string",
"const": "server_tool_result",
"title": "Type",
"default": "server_tool_result"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id"
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"default": "success"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": true,
"type": "object"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Output"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"tool_call_id"
],
"title": "ServerToolResult",
"description": "Result of a server-side / inline tool call, recorded in the same assistant message.\n\nMirrors LangChain's ``ServerToolResult``, except for ``output``. LangChain types that field\n``Any``, because its block is a cross-provider container. HAI fills it from one place only:\n``DeepAgentEngine._messages_from_tools_node`` assigns a LangChain ``ToolMessage.content`` of\ntype ``str | list[str | dict]``. A single text result, the common MCP case, arrives as a ``str``.\nSeveral parts, or a non-text part, arrive as a list of LangChain content blocks. A bare ``dict``\ncannot occur, so the type excludes it.\n\nUnlike ``ToolResult``, the structure here is given and not guessed, so the block keeps it.\nFlattening would destroy a multimodal result. ``None`` stays allowed, as in LangChain's\n``NotRequired``, so every stored row still reads. The anonymizer walks ``str`` values and nested\n``dict``/``list`` values."
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
},
"Function": {
"properties": {
"arguments": {
"type": "string",
"title": "Arguments"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"arguments",
"name"
],
"title": "Function"
},
"AttachmentMetaInfo": {
"properties": {
"file_id": {
"type": "string",
"title": "File Id",
"description": "file_id of the attachment."
},
"file_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Name",
"description": "Original name of the file, or null when it is unknown to the service."
},
"status": {
"$ref": "#/components/schemas/AttachmentStatus",
"description": "Whether the content was loaded and used for generation."
}
},
"type": "object",
"required": [
"file_id",
"status"
],
"title": "AttachmentMetaInfo",
"description": "Load result of one attachment of a run, exposed in the assistant message metadata.\n\nThe engine loads the content at inference time and reports per file whether it was usable for\ngeneration, so the consumer can display the outcome next to the file it attached."
},
"TokenUsage": {
"properties": {
"input_token": {
"type": "integer",
"title": "Input Token",
"description": "Number of input (prompt) tokens sent to the model",
"default": 0
},
"output_token": {
"type": "integer",
"title": "Output Token",
"description": "Number of output (completion) tokens generated by the model",
"default": 0
},
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "Total number of tokens used (input + output)",
"default": 0
}
},
"type": "object",
"title": "TokenUsage"
},
"AttachmentStatus": {
"type": "string",
"enum": [
"ok",
"not_found",
"error",
"empty"
],
"title": "AttachmentStatus",
"description": "Load outcome of a single attachment.\n\nExposed verbatim as the ``status`` field of the response metadata, so the values are part of the\npublic API contract. The LLM never sees the status itself: the engine renders it as a coarse\n```` flag (only OK is usable).\n\nOnly OK means the content was loaded and used for generation. NOT_FOUND, ERROR and EMPTY all\nmean \"not used\": the file was deleted on the storage service, could not be loaded, or holds no\nextractable text. EMPTY and ERROR do not imply the file is gone."
}
}
}
```
# Create a chat completion
```json
{
"method": "POST",
"path": "/v1/chat/completions",
"tags": [
"Chat Completions"
],
"summary": "Create a chat completion",
"description": "Returns an assistant response by sending one or more user messages. Does not stream the response.",
"operationId": "create_chat_completions_new_v1_chat_completions_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionsCreateNew"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssistantMessageRead"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"incorrect_stack_ending": {
"summary": "Incorrect Stack Ending",
"value": {
"error_code": "incorrect_stack_ending",
"detail": "The last message in the stack must be a user, tool, or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_stack_start": {
"summary": "Invalid Stack Start",
"value": {
"error_code": "invalid_stack_start",
"detail": "A message stack must start with a user or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"system_message_is_not_unique": {
"summary": "System Message Is Not Unique",
"value": {
"error_code": "system_message_is_not_unique",
"detail": "A thread can only contain one system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_is_not_unique": {
"summary": "Tool Message Is Not Unique",
"value": {
"error_code": "tool_message_is_not_unique",
"detail": "Tool message is not unique in the thread. There is a ToolMessage with the same id."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_message_must_follow_assistant_message": {
"summary": "User Message Must Follow Assistant Message",
"value": {
"error_code": "user_message_must_follow_assistant_message",
"detail": "A user message is expected after an assistant message without tool calls."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_message_follows_user_message": {
"summary": "Invalid Message Follows User Message",
"value": {
"error_code": "invalid_message_follows_user_message",
"detail": "Only an assistant or user message may follow a user message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_must_follow_assistant_message": {
"summary": "Tool Message Must Follow Assistant Message",
"value": {
"error_code": "tool_message_must_follow_assistant_message",
"detail": "Tool messages can only be posted after an assistant message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_has_no_matching_tool_call": {
"summary": "Tool Message Has No Matching Tool Call",
"value": {
"error_code": "tool_message_has_no_matching_tool_call",
"detail": "Tool message id not found in an preceding assistant message's tool calls in the thread"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_does_not_contain_all_tool_calls": {
"summary": "Thread Does Not Contain All Tool Calls",
"value": {
"error_code": "thread_does_not_contain_all_tool_calls",
"detail": "Thread does not contain all requested tool calls"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_empty": {
"summary": "Thread Empty",
"value": {
"error_code": "thread_empty",
"detail": "The thread is empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_last_message_invalid": {
"summary": "Thread Last Message Invalid",
"value": {
"error_code": "thread_last_message_invalid",
"detail": "Last message in the thread has to be a user, system or tool message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"content_filter_error": {
"summary": "Content Filter Error",
"value": {
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"engine_supports_streaming_only": {
"summary": "Engine Supports Streaming Only",
"value": {
"error_code": "engine_supports_streaming_only",
"detail": "The selected engine supports streaming responses only. Please use the streaming endpoint."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_id_conflicts_with_token": {
"summary": "User Id Conflicts With Token",
"value": {
"error_code": "user_id_conflicts_with_token",
"detail": "The user_id in the request differs from the user of the access token"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_persistence_mismatch": {
"summary": "Attachment Persistence Mismatch",
"value": {
"error_code": "attachment_persistence_mismatch",
"detail": "The attachment could not be stored due to an internal error."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"examples": {
"internal_service_error": {
"summary": "Internal Service Error",
"value": {
"error_code": "internal_service_error",
"detail": "An internal service required for processing the request is currently unavailable. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ChatCompletionsCreateNew": {
"properties": {
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id",
"description": "The ID of the assistant to invoke."
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id",
"description": "Optional end-user ID for tracking."
},
"messages": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/HumanMessageCreate"
},
{
"$ref": "#/components/schemas/SystemMessageCreate"
},
{
"$ref": "#/components/schemas/ToolMessageCreate"
},
{
"$ref": "#/components/schemas/AssistantMessageCreate"
}
],
"discriminator": {
"propertyName": "role",
"mapping": {
"assistant": "#/components/schemas/AssistantMessageCreate",
"system": "#/components/schemas/SystemMessageCreate",
"tool": "#/components/schemas/ToolMessageCreate",
"user": "#/components/schemas/HumanMessageCreate"
}
}
},
"type": "array",
"title": "Messages",
"description": "Array of messages forming the conversation context. Must contain at least one user message. The last message must be a user or tool message. At most one system message allowed. An assistant message must be preceded by a user message. An assistant message requesting tool calls must be immediately followed by the corresponding tool messages. For every tool message, a corresponding assistant message with the same tool_call_id must exist."
},
"meta_data": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestMetaData"
},
{
"type": "null"
}
],
"description": "Optional request metadata."
},
"tools": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCallParam"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "Tool definitions the assistant may call. If provided, tool_choice defaults to auto."
},
"tool_choice": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"auto",
"required"
]
},
{
"$ref": "#/components/schemas/MessageNamedToolChoiceParam"
},
{
"type": "null"
}
],
"title": "Tool Choice",
"description": "Controls which tool the model calls. Options: none, auto, or a named tool. Requires tools to be set."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"assistant_id",
"messages"
],
"title": "ChatCompletionsCreateNew",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"messages": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
}
],
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"messages": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt sowohl für den Arbeitgeber als auch für den Arbeitnehmer.",
"role": "assistant",
"sources": []
},
{
"content": "Kann die Probezeit verlängert werden?",
"role": "user"
}
],
"meta_data": {
"user_data": {
"licence": "PI123"
}
},
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
}
]
},
"AssistantMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"feedback": {
"anyOf": [
{
"$ref": "#/components/schemas/FeedbackMessageResponse"
},
{
"type": "null"
}
]
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at",
"sources"
],
"title": "AssistantMessageRead",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten.",
"created_at": "2025-03-15T09:13:02.654321Z",
"id": "5e6f7081-9012-def0-1234-556677889900",
"meta_data": {
"intent": "Kündigungsfrist Probezeit",
"legal_advice": false,
"type": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"content": "",
"created_at": "2025-03-15T09:13:05.000000Z",
"id": "6f708192-0123-ef01-2345-667788990011",
"role": "assistant",
"sources": [],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566",
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"HumanMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "user",
"title": "Role",
"default": "user"
},
"content": {
"type": "string",
"title": "Content",
"description": "The message text. Must be valid Unicode and non-empty. Maximum length: 30000 characters."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentCreate"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Optional file attachments. Maximum 3 attachment(s), each must be unique by file_id/user_id/base_url."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "HumanMessageCreate",
"examples": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"attachments": [
{
"file_id": "c3d4e5f6-7890-abcd-ef01-345678901234",
"user_id": "user_123"
}
],
"content": "Fasse den mitgeschickten Inhalt zusammen.",
"role": "user"
}
]
},
"SystemMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "system",
"title": "Role",
"default": "system"
},
"content": {
"type": "string",
"title": "Content",
"description": "System instructions for the assistant. Must be non-empty. Maximum length: 30000 characters."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "SystemMessageCreate",
"examples": [
{
"content": "Du bist ein Experte für deutsches Arbeitsrecht. Antworte stets auf Deutsch und verweise auf relevante Gesetzesgrundlagen.",
"role": "system"
}
]
},
"ToolMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "tool",
"title": "Role",
"default": "tool"
},
"content": {
"type": "string",
"title": "Content",
"description": "The tool execution result. Must be non-empty. Maximum length: 30000 characters."
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id",
"description": "The ID of the tool call this message responds to. Must match a tool_call_id from the preceding assistant message."
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"description": "The state of the tool run. Send \"error\" when the tool failed. Defaults to \"success\".",
"default": "success"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"tool_call_id"
],
"title": "ToolMessageCreate",
"examples": [
{
"content": "{\"results\": [{\"title\": \"§ 622 BGB Kündigungsfristen\", \"snippet\": \"Während einer vereinbarten Probezeit kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.\"}]}",
"role": "tool",
"status": "success",
"tool_call_id": "call_abc123"
}
]
},
"AssistantMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content",
"description": "The assistant response text. Maximum length: 30000 characters. Must be non-empty when tool_calls is absent. Must be empty if tool_calls is present."
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceCreate"
},
"type": "array",
"title": "Sources",
"description": "List of sources used as context for message generation"
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls",
"description": "The tool calls generated by the model, such as function calls."
},
"meta_data": {
"anyOf": [
{
"oneOf": [
{
"$ref": "#/components/schemas/LgAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/HRAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/CommonMetaDataModel"
},
{
"$ref": "#/components/schemas/DeepAgentMetaDataModel"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"53aa66b7-b874-407f-967c-3a959c919d62": "#/components/schemas/LgAgentMetaDataModel",
"689fa139-f46e-45e3-89a4-67efcde73114": "#/components/schemas/HRAgentMetaDataModel",
"6c1f6752-93e8-4b73-a946-2391f3dae805": "#/components/schemas/CommonMetaDataModel",
"f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f": "#/components/schemas/DeepAgentMetaDataModel"
}
}
},
{
"type": "null"
}
],
"title": "Meta Data",
"description": "Additional meta data for the assistant message. The meta_data response schema is dependent on the assistant.The schema is included in the assistant properties and can be retrieved via GET /assistants/{assistant_id}."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"sources"
],
"title": "AssistantMessageCreate",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten – sowohl Arbeitgeber als auch Arbeitnehmer können mit einer Frist von zwei Wochen kündigen.",
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
{
"content": "",
"role": "assistant",
"sources": [],
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"RequestMetaData": {
"properties": {
"user_data": {
"anyOf": [
{
"$ref": "#/components/schemas/UserData"
},
{
"type": "null"
}
]
}
},
"type": "object",
"title": "RequestMetaData"
},
"MessageToolCallParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageToolCallParam"
},
"MessageNamedToolChoiceParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionParam"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageNamedToolChoiceParam"
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
},
"FeedbackMessageResponse": {
"properties": {
"feedback": {
"$ref": "#/components/schemas/FeedbackOptions"
},
"negative_feedback_reason_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Negative Feedback Reason Id"
},
"negative_feedback_comment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Negative Feedback Comment"
}
},
"type": "object",
"required": [
"feedback"
],
"title": "FeedbackMessageResponse"
},
"MessageToolCall": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"function": {
"$ref": "#/components/schemas/Function"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"id",
"function",
"type"
],
"title": "MessageToolCall",
"description": "Structure of the tool call in the assistant message.\nThis corresponds to the LLM requesting to execute a tool."
},
"AttachmentCreate": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"base_url": {
"type": "string",
"title": "Base Url",
"default": "https://api.files.haufe.io"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "AttachmentCreate"
},
"SourceCreate": {
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Identifier of the source object."
},
"content": {
"type": "string",
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"meta_data"
],
"title": "SourceCreate"
},
"LgAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "53aa66b7-b874-407f-967c-3a959c919d62",
"title": "Type",
"default": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "Intent of the user query."
},
"legal_advice": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Legal Advice",
"description": "Indicates if the user query is a legal advice."
},
"rephrased_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rephrased Query",
"description": "Rephrased query if it was detected as legal advice."
},
"tool_call_info": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Call Info",
"description": "Information about the tool calls, such as function calls, parameters and results."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentMetaInfo"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments of the run as loaded by the engine, one entry per file with its load status."
}
},
"type": "object",
"required": [
"intent"
],
"title": "LgAgentMetaDataModel"
},
"HRAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "689fa139-f46e-45e3-89a4-67efcde73114",
"title": "Type",
"default": "689fa139-f46e-45e3-89a4-67efcde73114"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "The intent of the user query"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
}
},
"type": "object",
"required": [
"intent",
"finish_reason"
],
"title": "HRAgentMetaDataModel"
},
"CommonMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "6c1f6752-93e8-4b73-a946-2391f3dae805",
"title": "Type",
"default": "6c1f6752-93e8-4b73-a946-2391f3dae805"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detail",
"description": "Detail information about the error"
}
},
"type": "object",
"required": [
"finish_reason",
"detail"
],
"title": "CommonMetaDataModel"
},
"DeepAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f",
"title": "Type",
"default": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f"
},
"token_usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage information for the assistant message"
}
},
"type": "object",
"required": [
"token_usage"
],
"title": "DeepAgentMetaDataModel"
},
"UserData": {
"properties": {
"licence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Licence"
}
},
"type": "object",
"title": "UserData"
},
"FunctionDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"parameters": {
"additionalProperties": true,
"type": "object",
"title": "Parameters"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
}
},
"type": "object",
"required": [
"name",
"parameters"
],
"title": "FunctionDefinition"
},
"FunctionParam": {
"properties": {
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "FunctionParam"
},
"FeedbackOptions": {
"type": "string",
"enum": [
"positive",
"negative"
],
"title": "FeedbackOptions"
},
"Function": {
"properties": {
"arguments": {
"type": "string",
"title": "Arguments"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"arguments",
"name"
],
"title": "Function"
},
"AttachmentMetaInfo": {
"properties": {
"file_id": {
"type": "string",
"title": "File Id",
"description": "file_id of the attachment."
},
"file_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Name",
"description": "Original name of the file, or null when it is unknown to the service."
},
"status": {
"$ref": "#/components/schemas/AttachmentStatus",
"description": "Whether the content was loaded and used for generation."
}
},
"type": "object",
"required": [
"file_id",
"status"
],
"title": "AttachmentMetaInfo",
"description": "Load result of one attachment of a run, exposed in the assistant message metadata.\n\nThe engine loads the content at inference time and reports per file whether it was usable for\ngeneration, so the consumer can display the outcome next to the file it attached."
},
"TokenUsage": {
"properties": {
"input_token": {
"type": "integer",
"title": "Input Token",
"description": "Number of input (prompt) tokens sent to the model",
"default": 0
},
"output_token": {
"type": "integer",
"title": "Output Token",
"description": "Number of output (completion) tokens generated by the model",
"default": 0
},
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "Total number of tokens used (input + output)",
"default": 0
}
},
"type": "object",
"title": "TokenUsage"
},
"AttachmentStatus": {
"type": "string",
"enum": [
"ok",
"not_found",
"error",
"empty"
],
"title": "AttachmentStatus",
"description": "Load outcome of a single attachment.\n\nExposed verbatim as the ``status`` field of the response metadata, so the values are part of the\npublic API contract. The LLM never sees the status itself: the engine renders it as a coarse\n```` flag (only OK is usable).\n\nOnly OK means the content was loaded and used for generation. NOT_FOUND, ERROR and EMPTY all\nmean \"not used\": the file was deleted on the storage service, could not be loaded, or holds no\nextractable text. EMPTY and ERROR do not imply the file is gone."
}
}
}
```
# Stream a chat completion
```json
{
"method": "POST",
"path": "/v1/chat/completions/stream",
"tags": [
"Chat Completions"
],
"summary": "Stream a chat completion",
"description": "Streams an assistant response by sending one or more user messages. Returns an NDJSON stream.",
"operationId": "create_chat_completions_stream_new_v1_chat_completions_stream_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionsCreateNew"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageChunkResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"incorrect_stack_ending": {
"summary": "Incorrect Stack Ending",
"value": {
"error_code": "incorrect_stack_ending",
"detail": "The last message in the stack must be a user, tool, or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_stack_start": {
"summary": "Invalid Stack Start",
"value": {
"error_code": "invalid_stack_start",
"detail": "A message stack must start with a user or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"system_message_is_not_unique": {
"summary": "System Message Is Not Unique",
"value": {
"error_code": "system_message_is_not_unique",
"detail": "A thread can only contain one system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_is_not_unique": {
"summary": "Tool Message Is Not Unique",
"value": {
"error_code": "tool_message_is_not_unique",
"detail": "Tool message is not unique in the thread. There is a ToolMessage with the same id."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_message_must_follow_assistant_message": {
"summary": "User Message Must Follow Assistant Message",
"value": {
"error_code": "user_message_must_follow_assistant_message",
"detail": "A user message is expected after an assistant message without tool calls."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_message_follows_user_message": {
"summary": "Invalid Message Follows User Message",
"value": {
"error_code": "invalid_message_follows_user_message",
"detail": "Only an assistant or user message may follow a user message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_must_follow_assistant_message": {
"summary": "Tool Message Must Follow Assistant Message",
"value": {
"error_code": "tool_message_must_follow_assistant_message",
"detail": "Tool messages can only be posted after an assistant message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_has_no_matching_tool_call": {
"summary": "Tool Message Has No Matching Tool Call",
"value": {
"error_code": "tool_message_has_no_matching_tool_call",
"detail": "Tool message id not found in an preceding assistant message's tool calls in the thread"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_does_not_contain_all_tool_calls": {
"summary": "Thread Does Not Contain All Tool Calls",
"value": {
"error_code": "thread_does_not_contain_all_tool_calls",
"detail": "Thread does not contain all requested tool calls"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_empty": {
"summary": "Thread Empty",
"value": {
"error_code": "thread_empty",
"detail": "The thread is empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_last_message_invalid": {
"summary": "Thread Last Message Invalid",
"value": {
"error_code": "thread_last_message_invalid",
"detail": "Last message in the thread has to be a user, system or tool message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"content_filter_error": {
"summary": "Content Filter Error",
"value": {
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_id_conflicts_with_token": {
"summary": "User Id Conflicts With Token",
"value": {
"error_code": "user_id_conflicts_with_token",
"detail": "The user_id in the request differs from the user of the access token"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"engine_does_not_support_streaming": {
"summary": "Engine Does Not Support Streaming",
"value": {
"error_code": "engine_does_not_support_streaming",
"detail": "The selected engine does not support streaming responses. Please use the non-streaming endpoint."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_persistence_mismatch": {
"summary": "Attachment Persistence Mismatch",
"value": {
"error_code": "attachment_persistence_mismatch",
"detail": "The attachment could not be stored due to an internal error."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"examples": {
"internal_service_error": {
"summary": "Internal Service Error",
"value": {
"error_code": "internal_service_error",
"detail": "An internal service required for processing the request is currently unavailable. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ChatCompletionsCreateNew": {
"properties": {
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id",
"description": "The ID of the assistant to invoke."
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id",
"description": "Optional end-user ID for tracking."
},
"messages": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/HumanMessageCreate"
},
{
"$ref": "#/components/schemas/SystemMessageCreate"
},
{
"$ref": "#/components/schemas/ToolMessageCreate"
},
{
"$ref": "#/components/schemas/AssistantMessageCreate"
}
],
"discriminator": {
"propertyName": "role",
"mapping": {
"assistant": "#/components/schemas/AssistantMessageCreate",
"system": "#/components/schemas/SystemMessageCreate",
"tool": "#/components/schemas/ToolMessageCreate",
"user": "#/components/schemas/HumanMessageCreate"
}
}
},
"type": "array",
"title": "Messages",
"description": "Array of messages forming the conversation context. Must contain at least one user message. The last message must be a user or tool message. At most one system message allowed. An assistant message must be preceded by a user message. An assistant message requesting tool calls must be immediately followed by the corresponding tool messages. For every tool message, a corresponding assistant message with the same tool_call_id must exist."
},
"meta_data": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestMetaData"
},
{
"type": "null"
}
],
"description": "Optional request metadata."
},
"tools": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCallParam"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "Tool definitions the assistant may call. If provided, tool_choice defaults to auto."
},
"tool_choice": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"auto",
"required"
]
},
{
"$ref": "#/components/schemas/MessageNamedToolChoiceParam"
},
{
"type": "null"
}
],
"title": "Tool Choice",
"description": "Controls which tool the model calls. Options: none, auto, or a named tool. Requires tools to be set."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"assistant_id",
"messages"
],
"title": "ChatCompletionsCreateNew",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"messages": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
}
],
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"messages": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt sowohl für den Arbeitgeber als auch für den Arbeitnehmer.",
"role": "assistant",
"sources": []
},
{
"content": "Kann die Probezeit verlängert werden?",
"role": "user"
}
],
"meta_data": {
"user_data": {
"licence": "PI123"
}
},
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
}
]
},
"MessageChunkResponse": {
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"title": "Message Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"delta": {
"$ref": "#/components/schemas/MessageDeltaResponse"
}
},
"type": "object",
"required": [
"message_id",
"thread_id",
"created_at",
"delta"
],
"title": "MessageChunkResponse",
"description": "This object is the chunk representation that wraps an AssistantMessageRead during streaming.",
"examples": [
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content": "Während der Probezeit beträgt die Kündigungsfrist ",
"role": "assistant",
"sources": []
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content": "gemäß § 622 Abs. 3 BGB zwei Wochen.",
"meta_data": {
"intent": "Kündigungsfrist Probezeit",
"legal_advice": false
},
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit...",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"HumanMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "user",
"title": "Role",
"default": "user"
},
"content": {
"type": "string",
"title": "Content",
"description": "The message text. Must be valid Unicode and non-empty. Maximum length: 30000 characters."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentCreate"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Optional file attachments. Maximum 3 attachment(s), each must be unique by file_id/user_id/base_url."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "HumanMessageCreate",
"examples": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"attachments": [
{
"file_id": "c3d4e5f6-7890-abcd-ef01-345678901234",
"user_id": "user_123"
}
],
"content": "Fasse den mitgeschickten Inhalt zusammen.",
"role": "user"
}
]
},
"SystemMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "system",
"title": "Role",
"default": "system"
},
"content": {
"type": "string",
"title": "Content",
"description": "System instructions for the assistant. Must be non-empty. Maximum length: 30000 characters."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "SystemMessageCreate",
"examples": [
{
"content": "Du bist ein Experte für deutsches Arbeitsrecht. Antworte stets auf Deutsch und verweise auf relevante Gesetzesgrundlagen.",
"role": "system"
}
]
},
"ToolMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "tool",
"title": "Role",
"default": "tool"
},
"content": {
"type": "string",
"title": "Content",
"description": "The tool execution result. Must be non-empty. Maximum length: 30000 characters."
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id",
"description": "The ID of the tool call this message responds to. Must match a tool_call_id from the preceding assistant message."
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"description": "The state of the tool run. Send \"error\" when the tool failed. Defaults to \"success\".",
"default": "success"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"tool_call_id"
],
"title": "ToolMessageCreate",
"examples": [
{
"content": "{\"results\": [{\"title\": \"§ 622 BGB Kündigungsfristen\", \"snippet\": \"Während einer vereinbarten Probezeit kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.\"}]}",
"role": "tool",
"status": "success",
"tool_call_id": "call_abc123"
}
]
},
"AssistantMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content",
"description": "The assistant response text. Maximum length: 30000 characters. Must be non-empty when tool_calls is absent. Must be empty if tool_calls is present."
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceCreate"
},
"type": "array",
"title": "Sources",
"description": "List of sources used as context for message generation"
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls",
"description": "The tool calls generated by the model, such as function calls."
},
"meta_data": {
"anyOf": [
{
"oneOf": [
{
"$ref": "#/components/schemas/LgAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/HRAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/CommonMetaDataModel"
},
{
"$ref": "#/components/schemas/DeepAgentMetaDataModel"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"53aa66b7-b874-407f-967c-3a959c919d62": "#/components/schemas/LgAgentMetaDataModel",
"689fa139-f46e-45e3-89a4-67efcde73114": "#/components/schemas/HRAgentMetaDataModel",
"6c1f6752-93e8-4b73-a946-2391f3dae805": "#/components/schemas/CommonMetaDataModel",
"f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f": "#/components/schemas/DeepAgentMetaDataModel"
}
}
},
{
"type": "null"
}
],
"title": "Meta Data",
"description": "Additional meta data for the assistant message. The meta_data response schema is dependent on the assistant.The schema is included in the assistant properties and can be retrieved via GET /assistants/{assistant_id}."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"sources"
],
"title": "AssistantMessageCreate",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten – sowohl Arbeitgeber als auch Arbeitnehmer können mit einer Frist von zwei Wochen kündigen.",
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
{
"content": "",
"role": "assistant",
"sources": [],
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"RequestMetaData": {
"properties": {
"user_data": {
"anyOf": [
{
"$ref": "#/components/schemas/UserData"
},
{
"type": "null"
}
]
}
},
"type": "object",
"title": "RequestMetaData"
},
"MessageToolCallParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageToolCallParam"
},
"MessageNamedToolChoiceParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionParam"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageNamedToolChoiceParam"
},
"MessageDeltaResponse": {
"properties": {
"role": {
"$ref": "#/components/schemas/MessageRoleEnum"
},
"content": {
"type": "string",
"title": "Content"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
},
"tool_calls": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"role",
"content",
"sources"
],
"title": "MessageDeltaResponse",
"description": "This object is the Chunk representation of an AssistantMessageRead during streaming."
},
"AttachmentCreate": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"base_url": {
"type": "string",
"title": "Base Url",
"default": "https://api.files.haufe.io"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "AttachmentCreate"
},
"SourceCreate": {
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Identifier of the source object."
},
"content": {
"type": "string",
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"meta_data"
],
"title": "SourceCreate"
},
"MessageToolCall": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"function": {
"$ref": "#/components/schemas/Function"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"id",
"function",
"type"
],
"title": "MessageToolCall",
"description": "Structure of the tool call in the assistant message.\nThis corresponds to the LLM requesting to execute a tool."
},
"LgAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "53aa66b7-b874-407f-967c-3a959c919d62",
"title": "Type",
"default": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "Intent of the user query."
},
"legal_advice": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Legal Advice",
"description": "Indicates if the user query is a legal advice."
},
"rephrased_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rephrased Query",
"description": "Rephrased query if it was detected as legal advice."
},
"tool_call_info": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Call Info",
"description": "Information about the tool calls, such as function calls, parameters and results."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentMetaInfo"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments of the run as loaded by the engine, one entry per file with its load status."
}
},
"type": "object",
"required": [
"intent"
],
"title": "LgAgentMetaDataModel"
},
"HRAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "689fa139-f46e-45e3-89a4-67efcde73114",
"title": "Type",
"default": "689fa139-f46e-45e3-89a4-67efcde73114"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "The intent of the user query"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
}
},
"type": "object",
"required": [
"intent",
"finish_reason"
],
"title": "HRAgentMetaDataModel"
},
"CommonMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "6c1f6752-93e8-4b73-a946-2391f3dae805",
"title": "Type",
"default": "6c1f6752-93e8-4b73-a946-2391f3dae805"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detail",
"description": "Detail information about the error"
}
},
"type": "object",
"required": [
"finish_reason",
"detail"
],
"title": "CommonMetaDataModel"
},
"DeepAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f",
"title": "Type",
"default": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f"
},
"token_usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage information for the assistant message"
}
},
"type": "object",
"required": [
"token_usage"
],
"title": "DeepAgentMetaDataModel"
},
"UserData": {
"properties": {
"licence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Licence"
}
},
"type": "object",
"title": "UserData"
},
"FunctionDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"parameters": {
"additionalProperties": true,
"type": "object",
"title": "Parameters"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
}
},
"type": "object",
"required": [
"name",
"parameters"
],
"title": "FunctionDefinition"
},
"FunctionParam": {
"properties": {
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "FunctionParam"
},
"MessageRoleEnum": {
"type": "string",
"enum": [
"user",
"assistant",
"system",
"tool"
],
"title": "MessageRoleEnum"
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
},
"Function": {
"properties": {
"arguments": {
"type": "string",
"title": "Arguments"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"arguments",
"name"
],
"title": "Function"
},
"AttachmentMetaInfo": {
"properties": {
"file_id": {
"type": "string",
"title": "File Id",
"description": "file_id of the attachment."
},
"file_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Name",
"description": "Original name of the file, or null when it is unknown to the service."
},
"status": {
"$ref": "#/components/schemas/AttachmentStatus",
"description": "Whether the content was loaded and used for generation."
}
},
"type": "object",
"required": [
"file_id",
"status"
],
"title": "AttachmentMetaInfo",
"description": "Load result of one attachment of a run, exposed in the assistant message metadata.\n\nThe engine loads the content at inference time and reports per file whether it was usable for\ngeneration, so the consumer can display the outcome next to the file it attached."
},
"TokenUsage": {
"properties": {
"input_token": {
"type": "integer",
"title": "Input Token",
"description": "Number of input (prompt) tokens sent to the model",
"default": 0
},
"output_token": {
"type": "integer",
"title": "Output Token",
"description": "Number of output (completion) tokens generated by the model",
"default": 0
},
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "Total number of tokens used (input + output)",
"default": 0
}
},
"type": "object",
"title": "TokenUsage"
},
"AttachmentStatus": {
"type": "string",
"enum": [
"ok",
"not_found",
"error",
"empty"
],
"title": "AttachmentStatus",
"description": "Load outcome of a single attachment.\n\nExposed verbatim as the ``status`` field of the response metadata, so the values are part of the\npublic API contract. The LLM never sees the status itself: the engine renders it as a coarse\n```` flag (only OK is usable).\n\nOnly OK means the content was loaded and used for generation. NOT_FOUND, ERROR and EMPTY all\nmean \"not used\": the file was deleted on the storage service, could not be loaded, or holds no\nextractable text. EMPTY and ERROR do not imply the file is gone."
}
}
}
```
# Delete feedback
```json
{
"method": "DELETE",
"path": "/v1/threads/{thread_id}/messages/{message_id}/feedback",
"tags": [
"Feedback"
],
"summary": "Delete feedback",
"description": "Removes feedback from an assistant message.",
"operationId": "delete_feedback_message_v1_threads__thread_id__messages__message_id__feedback_delete",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
},
{
"name": "message_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Message Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"message_not_found": {
"summary": "Message Not Found",
"value": {
"error_code": "message_not_found",
"detail": "Message not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"feedback_not_found": {
"summary": "Feedback Not Found",
"value": {
"error_code": "feedback_not_found",
"detail": "Feedback not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
```
# List negative feedback reasons
```json
{
"method": "GET",
"path": "/v1/feedback/negative/reasons",
"tags": [
"Feedback"
],
"summary": "List negative feedback reasons",
"description": "Returns the available categorized reasons for negative feedback.",
"operationId": "get_feedback_reasons_v1_feedback_negative_reasons_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/NegativeFeedbackReasonResponse"
},
"type": "array",
"title": "Response Get Feedback Reasons V1 Feedback Negative Reasons Get"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"error_code": {
"type": "string",
"title": "Error Code"
},
"detail": {
"type": "string",
"title": "Detail"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"type": "object",
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"description": "Schema of the ServiceExceptions"
}
]
},
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"message": {
"type": "string",
"title": "Message"
}
},
"type": "object",
"required": [
"message"
],
"title": "GraviteeExceptionSchema"
}
]
},
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"properties": {
"error_code": {
"type": "string",
"title": "Error Code"
},
"detail": {
"type": "string",
"title": "Detail"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"type": "object",
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"description": "Schema of the ServiceExceptions"
}
]
},
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
}
}
}
}
},
"schemas": {
"NegativeFeedbackReasonResponse": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
}
},
"type": "object",
"required": [
"id",
"reason",
"description"
],
"title": "NegativeFeedbackReasonResponse",
"examples": [
{
"description": "Die Antwort enthielt sachlich falsche oder veraltete Informationen.",
"id": "d4e5f6a7-8901-bcde-f012-456789012345",
"reason": "Falsche Information"
},
{
"description": "Die Antwort ging nicht auf die gestellte Frage ein.",
"id": "e5f6a7b8-9012-cdef-0123-567890123456",
"reason": "Nicht hilfreich"
},
{
"description": "Wichtige Aspekte der Frage wurden nicht behandelt.",
"id": "f6a7b8c9-0123-def0-1234-678901234567",
"reason": "Unvollständig"
}
]
}
}
}
```
# Create or update feedback
```json
{
"method": "POST",
"path": "/v1/threads/{thread_id}/messages/{message_id}/feedback",
"tags": [
"Feedback"
],
"summary": "Create or update feedback",
"description": "Adds or overwrites user feedback on an assistant message. Positive feedback must not include a reason or comment.",
"operationId": "upsert_feedback_message_v1_threads__thread_id__messages__message_id__feedback_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
},
{
"name": "message_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Message Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeedbackMessage"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FeedbackMessageUpsertResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"feedback_request_error": {
"summary": "Feedback Request Error",
"value": {
"error_code": "feedback_request_error",
"detail": "Feedback cannot be attached to message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"message_not_found": {
"summary": "Message Not Found",
"value": {
"error_code": "message_not_found",
"detail": "Message not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"validation_error": {
"summary": "Invalid feedback payload",
"value": {
"error_code": "validation_error",
"detail": [
{
"loc": [
"body",
"feedback"
],
"message": "Input should be 'positive' or 'negative'",
"type": "enum"
}
]
},
"schema": {
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Detail",
"type": "array"
}
},
"required": [
"error_code",
"detail"
],
"title": "CustomRequestValidationErrorSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Detail",
"type": "array"
}
},
"required": [
"error_code",
"detail"
],
"title": "CustomRequestValidationErrorSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"FeedbackMessage": {
"properties": {
"feedback": {
"anyOf": [
{
"$ref": "#/components/schemas/FeedbackOptions"
},
{
"type": "null"
}
],
"description": "Feedback sentiment: positive or negative."
},
"negative_feedback_reason_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Negative Feedback Reason Id",
"description": "ID of a categorized negative feedback reason. Only allowed when feedback is negative."
},
"negative_feedback_comment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Negative Feedback Comment",
"description": "Optional free-text comment. Only allowed when feedback is negative. Maximum length: 2000 characters."
}
},
"type": "object",
"title": "FeedbackMessage",
"examples": [
{
"feedback": "positive"
},
{
"feedback": "negative",
"negative_feedback_comment": "Die Antwort war nicht hilfreich.",
"negative_feedback_reason_id": "d4e5f6a7-8901-bcde-f012-456789012345"
},
{
"feedback": "negative",
"negative_feedback_reason_id": "d4e5f6a7-8901-bcde-f012-456789012345"
}
]
},
"FeedbackMessageUpsertResponse": {
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"title": "Message Id"
},
"feedback": {
"anyOf": [
{
"$ref": "#/components/schemas/FeedbackOptions"
},
{
"type": "null"
}
]
},
"negative_feedback_reason_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Negative Feedback Reason Id"
},
"negative_feedback_comment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Negative Feedback Comment"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
}
},
"type": "object",
"required": [
"message_id",
"created_at"
],
"title": "FeedbackMessageUpsertResponse",
"examples": [
{
"created_at": "2025-03-15T10:00:00.000000Z",
"feedback": "positive",
"message_id": "5e6f7081-9012-def0-1234-556677889900"
},
{
"created_at": "2025-03-15T10:00:00.000000Z",
"feedback": "negative",
"last_updated_at": "2025-03-15T10:05:30.000000Z",
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"negative_feedback_comment": "Die Antwort enthielt veraltete Gesetzesverweise.",
"negative_feedback_reason_id": "d4e5f6a7-8901-bcde-f012-456789012345"
}
]
},
"FeedbackOptions": {
"type": "string",
"enum": [
"positive",
"negative"
],
"title": "FeedbackOptions"
}
}
}
```
# Delete a file
```json
{
"method": "DELETE",
"path": "/v1/files/{file_id}",
"tags": [
"Files"
],
"summary": "Delete a file",
"description": "Deletes the file. Files already attached to a thread stay available within that thread until the thread itself is deleted.",
"operationId": "delete_file_v1_files__file_id__delete",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "File Id"
}
},
{
"name": "user-id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"pattern": "^[A-Za-z0-9._\\-@:]+$",
"description": "ID of the end user the file belongs to.",
"title": "User-Id"
},
"description": "ID of the end user the file belongs to."
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {}
}
```
# Get file content
```json
{
"method": "GET",
"path": "/v1/files/{file_id}",
"tags": [
"Files"
],
"summary": "Get file content",
"description": "Returns the extracted text content of the file as plain text.",
"operationId": "get_file_content_v1_files__file_id__get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "File Id"
}
},
{
"name": "user-id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"pattern": "^[A-Za-z0-9._\\-@:]+$",
"description": "ID of the end user the file belongs to.",
"title": "User-Id"
},
"description": "ID of the end user the file belongs to."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {}
}
```
# Get file metadata
```json
{
"method": "GET",
"path": "/v1/files/{file_id}/metadata",
"tags": [
"Files"
],
"summary": "Get file metadata",
"description": "Returns the file name, chunk and character counts, and the AI-extracted metadata of a file, such as language, summary, domain, document kind and author. The AI-extracted fields are populated once `extraction_status` is `completed`.",
"operationId": "get_file_metadata_v1_files__file_id__metadata_get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "File Id"
}
},
{
"name": "user-id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"pattern": "^[A-Za-z0-9._\\-@:]+$",
"description": "ID of the end user the file belongs to.",
"title": "User-Id"
},
"description": "ID of the end user the file belongs to."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileMetadataResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"FileMetadataResponse": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"file_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Name"
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Summary"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Language"
},
"document_kind": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Kind"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"tags": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/FileTag"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags"
},
"chunks_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Chunks Count"
},
"characters_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Characters Count"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "FileMetadataResponse",
"examples": [
{
"characters_count": 24680,
"chunks_count": 12,
"document_kind": "Report",
"domain": "Finance",
"file_id": "360d942f-d861-4611-b4b3-227278c9e709",
"file_name": "q3-financial-results.pdf",
"language": "en",
"summary": "This document covers quarterly financial results for Q3 2025.",
"tags": [
{
"ai_extracted": true,
"key": "author",
"value": "Jane Doe"
},
{
"ai_extracted": true,
"key": "created_date",
"value": "2025-09-30"
}
]
}
]
},
"FileTag": {
"properties": {
"key": {
"type": "string",
"title": "Key"
},
"value": {
"title": "Value"
},
"ai_extracted": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Ai Extracted"
}
},
"type": "object",
"required": [
"key"
],
"title": "FileTag",
"description": "A single key-value metadata field of a file (e.g. author, created_date)."
}
}
}
```
# Get file processing status
```json
{
"method": "GET",
"path": "/v1/files/{file_id}/status",
"tags": [
"Files"
],
"summary": "Get file processing status",
"description": "Returns the current processing status, pipeline steps, and warnings. Poll until `processingStatus` is `PROCESSED` before attaching the file to a message.",
"operationId": "get_file_status_v1_files__file_id__status_get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "File Id"
}
},
{
"name": "user-id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"pattern": "^[A-Za-z0-9._\\-@:]+$",
"description": "ID of the end user the file belongs to.",
"title": "User-Id"
},
"description": "ID of the end user the file belongs to."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileStatusResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"FileStatusResponse": {
"properties": {
"processing_status": {
"$ref": "#/components/schemas/ProcessingStatus"
},
"processing_steps": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Processing Steps"
},
"validation_steps": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Validation Steps"
},
"warnings": {
"$ref": "#/components/schemas/FileStatusWarnings"
}
},
"type": "object",
"required": [
"processing_status",
"processing_steps",
"validation_steps",
"warnings"
],
"title": "FileStatusResponse",
"examples": [
{
"processing_status": "PROCESSING",
"processing_steps": [
{
"createdAt": "2026-04-15T09:43:13.247Z",
"endedAt": "2026-04-15T09:43:14.204Z",
"status": "ANTIVIRUS_SCANNING"
}
],
"warnings": {
"empty": false,
"infected": false,
"length": false
}
},
{
"processing_status": "FAILED",
"processing_steps": [
{
"createdAt": "2026-04-15T09:43:13.247Z",
"endedAt": "2026-04-15T09:43:14.204Z",
"status": "ANTIVIRUS_SCANNING"
},
{
"createdAt": "2026-04-15T09:43:14.700Z",
"endedAt": "2026-04-15T09:44:53.330Z",
"status": "PROCESSING"
},
{
"createdAt": "2026-04-15T09:44:53.430Z",
"endedAt": "2026-04-15T09:45:13.599Z",
"status": "CHUNKING"
}
],
"validation_steps": [
{
"content_validation": "Content Validation failed. The file is empty or it's length exceeds the 60000 characters"
}
],
"warnings": {
"empty": false,
"infected": false,
"length": true
}
}
]
},
"ProcessingStatus": {
"type": "string",
"enum": [
"PROCESSED",
"PROCESSING",
"FAILED",
"PENDING_UPLOAD",
"ANTIVIRUS_SCANNING",
"UNKNOWN"
],
"title": "ProcessingStatus",
"description": "Status of Nuvio's upload and processing lifecycle."
},
"FileStatusWarnings": {
"properties": {
"length": {
"type": "boolean",
"title": "Length"
},
"infected": {
"type": "boolean",
"title": "Infected"
},
"empty": {
"type": "boolean",
"title": "Empty"
}
},
"type": "object",
"required": [
"length",
"infected",
"empty"
],
"title": "FileStatusWarnings"
}
}
}
```
# Request an upload URL
```json
{
"method": "GET",
"path": "/v1/files/signed-url",
"tags": [
"Files"
],
"summary": "Request an upload URL",
"description": "Returns a pre-signed URL and a `file_id`. Upload your file via HTTP PUT to the returned `file_url`. Then poll `GET /files/{file_id}/status` until processing is complete, and attach the `file_id` to a message.",
"operationId": "get_signed_url_v1_files_signed_url_get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "filename",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "File name including its extension (e.g. `report.pdf`).",
"title": "Filename"
},
"description": "File name including its extension (e.g. `report.pdf`)."
},
{
"name": "persist",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If `true` (default), the file is kept for reuse. If `false`, it is removed after 24h.",
"default": true,
"title": "Persist"
},
"description": "If `true` (default), the file is kept for reuse. If `false`, it is removed after 24h."
},
{
"name": "user-id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"pattern": "^[A-Za-z0-9._\\-@:]+$",
"description": "ID of the end user the file belongs to.",
"title": "User-Id"
},
"description": "ID of the end user the file belongs to."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignedUrlResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"SignedUrlResponse": {
"properties": {
"expires_in": {
"type": "integer",
"title": "Expires In"
},
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"file_url": {
"type": "string",
"title": "File Url"
},
"file_limits": {
"$ref": "#/components/schemas/FileLimits"
}
},
"type": "object",
"required": [
"expires_in",
"file_id",
"file_url",
"file_limits"
],
"title": "SignedUrlResponse",
"examples": [
{
"expires_in": 600,
"file_id": "360d942f-d861-4611-b4b3-227278c9e709",
"file_limits": {
"allowed_types": [
"text/csv",
"text/plain",
"application/pdf",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
],
"max_size": 10485760
},
"file_url": "https://hg-ppi-s3-goatlab-dev-files..."
}
]
},
"FileLimits": {
"properties": {
"max_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Size"
},
"allowed_types": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Allowed Types"
}
},
"type": "object",
"title": "FileLimits"
}
}
}
```
# List files
```json
{
"method": "GET",
"path": "/v1/files",
"tags": [
"Files"
],
"summary": "List files",
"description": "Lists files for the given user, paginated.",
"operationId": "list_files_v1_files_get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number, 1-based.",
"default": 1,
"title": "Page"
},
"description": "Page number, 1-based."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Number of files per page (max 100).",
"default": 30,
"title": "Limit"
},
"description": "Number of files per page (max 100)."
},
{
"name": "user-id",
"in": "header",
"required": true,
"schema": {
"type": "string",
"maxLength": 255,
"pattern": "^[A-Za-z0-9._\\-@:]+$",
"description": "ID of the end user the file belongs to.",
"title": "User-Id"
},
"description": "ID of the end user the file belongs to."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileListResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"FileListResponse": {
"properties": {
"files": {
"items": {
"$ref": "#/components/schemas/FileInfo"
},
"type": "array",
"title": "Files"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"page": {
"type": "integer",
"title": "Page"
},
"total": {
"type": "integer",
"title": "Total"
}
},
"type": "object",
"required": [
"files",
"limit",
"page",
"total"
],
"title": "FileListResponse",
"examples": [
{
"files": [
{
"characters_count": 24680,
"chunks_count": 12,
"file_id": "9c3e00fe-1b42-413a-bf44-39ad9491ad86",
"file_name": "test-file-reisekostenabrechnung.pdf"
},
{
"characters_count": 15320,
"chunks_count": 8,
"file_id": "cbfe557e-144e-43f3-823f-d72be00084a2",
"file_name": "test-file-reisekostenabrechnung.pdf"
}
],
"limit": 30,
"page": 1,
"total": 4
}
]
},
"FileInfo": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"file_name": {
"type": "string",
"title": "File Name"
},
"extraction_status": {
"anyOf": [
{
"$ref": "#/components/schemas/ExtractionStatus"
},
{
"type": "null"
}
]
},
"chunks_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Chunks Count"
},
"characters_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Characters Count"
}
},
"type": "object",
"required": [
"file_id",
"file_name"
],
"title": "FileInfo"
},
"ExtractionStatus": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed",
"unknown"
],
"title": "ExtractionStatus",
"description": "Status of the AI metadata extraction, in the casing of the Agents API contract."
}
}
}
```
# Health probe
```json
{
"method": "GET",
"path": "/health",
"tags": [
"Healthchecks"
],
"summary": "Health probe",
"operationId": "handler_health_get",
"responses": {
"200": {
"description": "Successful Response"
}
},
"security": [],
"description": "Returns overall service health status.",
"schemas": {}
}
```
# Liveness probe
```json
{
"method": "GET",
"path": "/health/liveness",
"tags": [
"Healthchecks"
],
"summary": "Liveness probe",
"operationId": "handler_health_liveness_get",
"responses": {
"200": {
"description": "Successful Response"
}
},
"security": [],
"description": "Returns whether the service process is running.",
"schemas": {}
}
```
# Readiness probe
```json
{
"method": "GET",
"path": "/health/readiness",
"tags": [
"Healthchecks"
],
"summary": "Readiness probe",
"operationId": "handler_health_readiness_get",
"responses": {
"200": {
"description": "Successful Response"
}
},
"security": [],
"description": "Returns whether the service is ready to accept requests.",
"schemas": {}
}
```
# Create a message
```json
{
"method": "POST",
"path": "/v1/threads/{thread_id}/messages",
"tags": [
"Threads"
],
"summary": "Create a message",
"description": "Adds a message to a thread's message stack. Supports user, system, tool, and assistant roles. Cannot add messages to threads created via Chat Completions. Tool messages must follow an assistant message whose tool_call_id matches. System messages should be the first message in a thread.",
"operationId": "create_messages_new",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/HumanMessageCreate"
},
{
"$ref": "#/components/schemas/SystemMessageCreate"
},
{
"$ref": "#/components/schemas/ToolMessageCreate"
},
{
"$ref": "#/components/schemas/AssistantMessageCreate"
}
],
"discriminator": {
"propertyName": "role",
"mapping": {
"user": "#/components/schemas/HumanMessageCreate",
"system": "#/components/schemas/SystemMessageCreate",
"tool": "#/components/schemas/ToolMessageCreate",
"assistant": "#/components/schemas/AssistantMessageCreate"
}
},
"title": "Message Create"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/HumanMessageRead"
},
{
"$ref": "#/components/schemas/SystemMessageRead"
},
{
"$ref": "#/components/schemas/ToolMessageRead"
},
{
"$ref": "#/components/schemas/AssistantMessageRead"
}
],
"discriminator": {
"propertyName": "role",
"mapping": {
"user": "#/components/schemas/HumanMessageRead",
"system": "#/components/schemas/SystemMessageRead",
"tool": "#/components/schemas/ToolMessageRead",
"assistant": "#/components/schemas/AssistantMessageRead"
}
},
"title": "Response Create Messages New"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"system_message_is_not_unique": {
"summary": "System Message Is Not Unique",
"value": {
"error_code": "system_message_is_not_unique",
"detail": "A thread can only contain one system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_message_must_follow_assistant_message": {
"summary": "User Message Must Follow Assistant Message",
"value": {
"error_code": "user_message_must_follow_assistant_message",
"detail": "A user message is expected after an assistant message without tool calls."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_message_follows_user_message": {
"summary": "Invalid Message Follows User Message",
"value": {
"error_code": "invalid_message_follows_user_message",
"detail": "Only an assistant or user message may follow a user message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_must_follow_assistant_message": {
"summary": "Tool Message Must Follow Assistant Message",
"value": {
"error_code": "tool_message_must_follow_assistant_message",
"detail": "Tool messages can only be posted after an assistant message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_has_no_matching_tool_call": {
"summary": "Tool Message Has No Matching Tool Call",
"value": {
"error_code": "tool_message_has_no_matching_tool_call",
"detail": "Tool message id not found in an preceding assistant message's tool calls in the thread"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"tool_message_is_not_unique": {
"summary": "Tool Message Is Not Unique",
"value": {
"error_code": "tool_message_is_not_unique",
"detail": "Tool message is not unique in the thread. There is a ToolMessage with the same id."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"invalid_stack_start": {
"summary": "Invalid Stack Start",
"value": {
"error_code": "invalid_stack_start",
"detail": "A message stack must start with a user or system message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_raised_an_error": {
"summary": "Attachment Document Raised An Error",
"value": {
"error_code": "attachment_document_raised_an_error",
"detail": "The file attachment service has raised an error. Please try again later"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_access_forbidden": {
"summary": "Attachment Access Forbidden",
"value": {
"error_code": "attachment_access_forbidden",
"detail": "You do not have permission to access this attachment."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"message_not_found": {
"summary": "Message Not Found",
"value": {
"error_code": "message_not_found",
"detail": "Message not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_does_not_exist": {
"summary": "Attachment Document Does Not Exist",
"value": {
"error_code": "attachment_document_does_not_exist",
"detail": "Document with `file_id` is not available for the user with `user_id` on the document server."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"conflict": {
"summary": "Conflict",
"value": {
"error_code": "conflict",
"detail": "Conflict - File is infected with a virus or it's still being processed"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_document_still_processing": {
"summary": "Attachment Document Still Processing",
"value": {
"error_code": "attachment_document_still_processing",
"detail": "The file attachment is still being processed. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"message_content_empty": {
"summary": "Message Content Empty",
"value": {
"error_code": "message_content_empty",
"detail": "Message content cannot be empty."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"assistant_message_content_empty": {
"summary": "Assistant Message Content Empty",
"value": {
"error_code": "assistant_message_content_empty",
"detail": "Either a tool call or content must be provided for an assistant message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"assistant_message_content_and_tool_calls_present": {
"summary": "Assistant Message Content And Tool Calls Present",
"value": {
"error_code": "assistant_message_content_and_tool_calls_present",
"detail": "Assistant message cannot have both content and tool calls present."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"message_content_too_long": {
"summary": "Message Content Too Long",
"value": {
"error_code": "message_content_too_long",
"detail": "Message content exceeds the maximum allowed length of 30000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"message_invalid_for_engine": {
"summary": "Message Invalid For Engine",
"value": {
"error_code": "message_invalid_for_engine",
"detail": "The message content does not match the schema the assistant's engine expects. See the engine's tool message schema in the assistant documentation."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_message_too_many_attachments": {
"summary": "User Message Too Many Attachments",
"value": {
"error_code": "user_message_too_many_attachments",
"detail": "You cannot attach more than 3 attachments to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"user_message_not_unique_attachments": {
"summary": "User Message Not Unique Attachments",
"value": {
"error_code": "user_message_not_unique_attachments",
"detail": "You cannot attach the same attachment multiple times to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"unprocessable_character": {
"summary": "Unprocessable Character",
"value": {
"error_code": "unprocessable_character",
"detail": "String contains characters that cannot be encoded in UTF-8."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_url_invalid": {
"summary": "Attachment Url Invalid",
"value": {
"error_code": "attachment_url_invalid",
"detail": "The provided base_url is not valid."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_exceeds_max_size": {
"summary": "Attachment Exceeds Max Size",
"value": {
"error_code": "attachment_exceeds_max_size",
"detail": "Attachment content cannot be longer than 60000 characters."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_is_below_minimum_size": {
"summary": "Attachment Is Below Minimum Size",
"value": {
"error_code": "attachment_is_below_minimum_size",
"detail": "Attachment content is empty: no text could be extracted from the file."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_requires_user_id": {
"summary": "Attachment Requires User Id",
"value": {
"error_code": "attachment_requires_user_id",
"detail": "A non-empty user_id is required either in the thread or in the attachment when attaching a file to a message."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"attachment_not_unique": {
"summary": "Attachment Not Unique",
"value": {
"error_code": "attachment_not_unique",
"detail": "Attachments must be unique by (file_id, user_id, base_url). The same file was provided more than once."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"attachment_persistence_mismatch": {
"summary": "Attachment Persistence Mismatch",
"value": {
"error_code": "attachment_persistence_mismatch",
"detail": "The attachment could not be stored due to an internal error."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"examples": {
"attachment_document_not_reachable": {
"summary": "Attachment Document Not Reachable",
"value": {
"error_code": "attachment_document_not_reachable",
"detail": "The file attachment service does not respond as expected. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"examples": {
"internal_service_error": {
"summary": "Internal Service Error",
"value": {
"error_code": "internal_service_error",
"detail": "An internal service required for processing the request is currently unavailable. Please try again later."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"HumanMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "user",
"title": "Role",
"default": "user"
},
"content": {
"type": "string",
"title": "Content",
"description": "The message text. Must be valid Unicode and non-empty. Maximum length: 30000 characters."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentCreate"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Optional file attachments. Maximum 3 attachment(s), each must be unique by file_id/user_id/base_url."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "HumanMessageCreate",
"examples": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"role": "user"
},
{
"attachments": [
{
"file_id": "c3d4e5f6-7890-abcd-ef01-345678901234",
"user_id": "user_123"
}
],
"content": "Fasse den mitgeschickten Inhalt zusammen.",
"role": "user"
}
]
},
"SystemMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "system",
"title": "Role",
"default": "system"
},
"content": {
"type": "string",
"title": "Content",
"description": "System instructions for the assistant. Must be non-empty. Maximum length: 30000 characters."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content"
],
"title": "SystemMessageCreate",
"examples": [
{
"content": "Du bist ein Experte für deutsches Arbeitsrecht. Antworte stets auf Deutsch und verweise auf relevante Gesetzesgrundlagen.",
"role": "system"
}
]
},
"ToolMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "tool",
"title": "Role",
"default": "tool"
},
"content": {
"type": "string",
"title": "Content",
"description": "The tool execution result. Must be non-empty. Maximum length: 30000 characters."
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id",
"description": "The ID of the tool call this message responds to. Must match a tool_call_id from the preceding assistant message."
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"description": "The state of the tool run. Send \"error\" when the tool failed. Defaults to \"success\".",
"default": "success"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"tool_call_id"
],
"title": "ToolMessageCreate",
"examples": [
{
"content": "{\"results\": [{\"title\": \"§ 622 BGB Kündigungsfristen\", \"snippet\": \"Während einer vereinbarten Probezeit kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.\"}]}",
"role": "tool",
"status": "success",
"tool_call_id": "call_abc123"
}
]
},
"AssistantMessageCreate": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content",
"description": "The assistant response text. Maximum length: 30000 characters. Must be non-empty when tool_calls is absent. Must be empty if tool_calls is present."
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceCreate"
},
"type": "array",
"title": "Sources",
"description": "List of sources used as context for message generation"
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls",
"description": "The tool calls generated by the model, such as function calls."
},
"meta_data": {
"anyOf": [
{
"oneOf": [
{
"$ref": "#/components/schemas/LgAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/HRAgentMetaDataModel"
},
{
"$ref": "#/components/schemas/CommonMetaDataModel"
},
{
"$ref": "#/components/schemas/DeepAgentMetaDataModel"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"53aa66b7-b874-407f-967c-3a959c919d62": "#/components/schemas/LgAgentMetaDataModel",
"689fa139-f46e-45e3-89a4-67efcde73114": "#/components/schemas/HRAgentMetaDataModel",
"6c1f6752-93e8-4b73-a946-2391f3dae805": "#/components/schemas/CommonMetaDataModel",
"f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f": "#/components/schemas/DeepAgentMetaDataModel"
}
}
},
{
"type": "null"
}
],
"title": "Meta Data",
"description": "Additional meta data for the assistant message. The meta_data response schema is dependent on the assistant.The schema is included in the assistant properties and can be retrieved via GET /assistants/{assistant_id}."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"sources"
],
"title": "AssistantMessageCreate",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten – sowohl Arbeitgeber als auch Arbeitnehmer können mit einer Frist von zwei Wochen kündigen.",
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
{
"content": "",
"role": "assistant",
"sources": [],
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"HumanMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "user",
"title": "Role",
"default": "user"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentRead"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at"
],
"title": "HumanMessageRead",
"examples": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"created_at": "2025-03-15T09:12:45.123456Z",
"id": "4d5e6f70-8901-cdef-0123-445566778899",
"role": "user",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"SystemMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "system",
"title": "Role",
"default": "system"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at"
],
"title": "SystemMessageRead",
"examples": [
{
"content": "Du bist ein Experte für deutsches Arbeitsrecht. Antworte stets auf Deutsch und verweise auf relevante Gesetzesgrundlagen.",
"created_at": "2025-03-15T09:12:33.456789Z",
"id": "7a8b9c0d-1234-abcd-ef01-778899001122",
"role": "system",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"ToolMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "tool",
"title": "Role",
"default": "tool"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id"
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"description": "The state of the tool run.",
"default": "success"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at",
"tool_call_id"
],
"title": "ToolMessageRead",
"examples": [
{
"content": "{\"results\": [{\"title\": \"§ 622 BGB Kündigungsfristen\", \"snippet\": \"Während einer vereinbarten Probezeit kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.\"}]}",
"created_at": "2025-03-15T09:13:06.000000Z",
"id": "8b9c0d1e-2345-bcde-f012-889900112233",
"role": "tool",
"status": "success",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566",
"tool_call_id": "call_abc123"
}
]
},
"AssistantMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"feedback": {
"anyOf": [
{
"$ref": "#/components/schemas/FeedbackMessageResponse"
},
{
"type": "null"
}
]
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at",
"sources"
],
"title": "AssistantMessageRead",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten.",
"created_at": "2025-03-15T09:13:02.654321Z",
"id": "5e6f7081-9012-def0-1234-556677889900",
"meta_data": {
"intent": "Kündigungsfrist Probezeit",
"legal_advice": false,
"type": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"content": "",
"created_at": "2025-03-15T09:13:05.000000Z",
"id": "6f708192-0123-ef01-2345-667788990011",
"role": "assistant",
"sources": [],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566",
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"AttachmentCreate": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"base_url": {
"type": "string",
"title": "Base Url",
"default": "https://api.files.haufe.io"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "AttachmentCreate"
},
"SourceCreate": {
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Identifier of the source object."
},
"content": {
"type": "string",
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"meta_data"
],
"title": "SourceCreate"
},
"MessageToolCall": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"function": {
"$ref": "#/components/schemas/Function"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"id",
"function",
"type"
],
"title": "MessageToolCall",
"description": "Structure of the tool call in the assistant message.\nThis corresponds to the LLM requesting to execute a tool."
},
"LgAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "53aa66b7-b874-407f-967c-3a959c919d62",
"title": "Type",
"default": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "Intent of the user query."
},
"legal_advice": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Legal Advice",
"description": "Indicates if the user query is a legal advice."
},
"rephrased_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Rephrased Query",
"description": "Rephrased query if it was detected as legal advice."
},
"tool_call_info": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Call Info",
"description": "Information about the tool calls, such as function calls, parameters and results."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentMetaInfo"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments of the run as loaded by the engine, one entry per file with its load status."
}
},
"type": "object",
"required": [
"intent"
],
"title": "LgAgentMetaDataModel"
},
"HRAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "689fa139-f46e-45e3-89a4-67efcde73114",
"title": "Type",
"default": "689fa139-f46e-45e3-89a4-67efcde73114"
},
"intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Intent",
"description": "The intent of the user query"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
}
},
"type": "object",
"required": [
"intent",
"finish_reason"
],
"title": "HRAgentMetaDataModel"
},
"CommonMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "6c1f6752-93e8-4b73-a946-2391f3dae805",
"title": "Type",
"default": "6c1f6752-93e8-4b73-a946-2391f3dae805"
},
"finish_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Finish Reason",
"description": "Reason why the assistant finished the conversation"
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detail",
"description": "Detail information about the error"
}
},
"type": "object",
"required": [
"finish_reason",
"detail"
],
"title": "CommonMetaDataModel"
},
"DeepAgentMetaDataModel": {
"properties": {
"type": {
"type": "string",
"const": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f",
"title": "Type",
"default": "f1e3c5b0-8d4a-4f9e-9c2b-1a2b3c4d5e6f"
},
"token_usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage information for the assistant message"
}
},
"type": "object",
"required": [
"token_usage"
],
"title": "DeepAgentMetaDataModel"
},
"AttachmentRead": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "AttachmentRead",
"description": "Response object for the attachment endpoint.\n\nWe do not expose the content for payload size reasons."
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
},
"FeedbackMessageResponse": {
"properties": {
"feedback": {
"$ref": "#/components/schemas/FeedbackOptions"
},
"negative_feedback_reason_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Negative Feedback Reason Id"
},
"negative_feedback_comment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Negative Feedback Comment"
}
},
"type": "object",
"required": [
"feedback"
],
"title": "FeedbackMessageResponse"
},
"Function": {
"properties": {
"arguments": {
"type": "string",
"title": "Arguments"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"arguments",
"name"
],
"title": "Function"
},
"AttachmentMetaInfo": {
"properties": {
"file_id": {
"type": "string",
"title": "File Id",
"description": "file_id of the attachment."
},
"file_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "File Name",
"description": "Original name of the file, or null when it is unknown to the service."
},
"status": {
"$ref": "#/components/schemas/AttachmentStatus",
"description": "Whether the content was loaded and used for generation."
}
},
"type": "object",
"required": [
"file_id",
"status"
],
"title": "AttachmentMetaInfo",
"description": "Load result of one attachment of a run, exposed in the assistant message metadata.\n\nThe engine loads the content at inference time and reports per file whether it was usable for\ngeneration, so the consumer can display the outcome next to the file it attached."
},
"TokenUsage": {
"properties": {
"input_token": {
"type": "integer",
"title": "Input Token",
"description": "Number of input (prompt) tokens sent to the model",
"default": 0
},
"output_token": {
"type": "integer",
"title": "Output Token",
"description": "Number of output (completion) tokens generated by the model",
"default": 0
},
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "Total number of tokens used (input + output)",
"default": 0
}
},
"type": "object",
"title": "TokenUsage"
},
"FeedbackOptions": {
"type": "string",
"enum": [
"positive",
"negative"
],
"title": "FeedbackOptions"
},
"AttachmentStatus": {
"type": "string",
"enum": [
"ok",
"not_found",
"error",
"empty"
],
"title": "AttachmentStatus",
"description": "Load outcome of a single attachment.\n\nExposed verbatim as the ``status`` field of the response metadata, so the values are part of the\npublic API contract. The LLM never sees the status itself: the engine renders it as a coarse\n```` flag (only OK is usable).\n\nOnly OK means the content was loaded and used for generation. NOT_FOUND, ERROR and EMPTY all\nmean \"not used\": the file was deleted on the storage service, could not be loaded, or holds no\nextractable text. EMPTY and ERROR do not imply the file is gone."
}
}
}
```
# Stream a run
```json
{
"method": "POST",
"path": "/v1/threads/{thread_id}/run/events/stream",
"tags": [
"Threads"
],
"summary": "Stream a run",
"description": "Invokes the assistant on a thread and streams the response as NDJSON with a list of content blocks.",
"operationId": "create_run_events_stream_v1_threads__thread_id__run_events_stream_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageEventsChunkResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"content_filter_error": {
"summary": "Content Filter Error",
"value": {
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_does_not_contain_all_tool_calls": {
"summary": "Thread Does Not Contain All Tool Calls",
"value": {
"error_code": "thread_does_not_contain_all_tool_calls",
"detail": "Thread does not contain all requested tool calls"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_empty": {
"summary": "Thread Empty",
"value": {
"error_code": "thread_empty",
"detail": "The thread is empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_last_message_invalid": {
"summary": "Thread Last Message Invalid",
"value": {
"error_code": "thread_last_message_invalid",
"detail": "Last message in the thread has to be a user, system or tool message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"assistant_is_missing": {
"summary": "Assistant Is Missing",
"value": {
"error_code": "assistant_is_missing",
"detail": "Assistant is missing"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"RunCreate": {
"properties": {
"meta_data": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestMetaData"
},
{
"type": "null"
}
],
"description": "Optional request metadata."
},
"tools": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCallParam"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "Tool definitions the assistant may call."
},
"tool_choice": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"auto",
"required"
]
},
{
"$ref": "#/components/schemas/MessageNamedToolChoiceParam"
},
{
"type": "null"
}
],
"title": "Tool Choice",
"description": "Controls which tool the model calls. Requires tools to be set."
}
},
"type": "object",
"title": "RunCreate",
"examples": [
{},
{
"meta_data": {
"user_data": {
"licence": "PI123"
}
}
},
{
"meta_data": {
"user_data": {
"licence": "PI123"
}
},
"tool_choice": "auto",
"tools": [
{
"function": {
"description": "Search the knowledge base for relevant legal documents.",
"name": "search_documents",
"parameters": {
"properties": {
"query": {
"description": "The search query.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
},
"type": "function"
}
]
}
]
},
"MessageEventsChunkResponse": {
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"title": "Message Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"delta": {
"$ref": "#/components/schemas/AssistantMessageEventsDeltaRead"
}
},
"type": "object",
"required": [
"message_id",
"thread_id",
"created_at",
"delta"
],
"title": "MessageEventsChunkResponse",
"description": "Streaming chunk yielded by POST /v1/threads/{thread_id}/run/events/stream.\n\nThe content-block counterpart to MessageChunkResponse: delta.content_blocks is list[ContentBlock]\ninstead of str.",
"examples": [
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content_blocks": [
{
"reasoning": "The user is asking about notice periods during probation.",
"type": "reasoning"
}
],
"role": "assistant",
"sources": []
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content_blocks": [
{
"text": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen.",
"type": "text"
}
],
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit...",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"RequestMetaData": {
"properties": {
"user_data": {
"anyOf": [
{
"$ref": "#/components/schemas/UserData"
},
{
"type": "null"
}
]
}
},
"type": "object",
"title": "RequestMetaData"
},
"MessageToolCallParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageToolCallParam"
},
"MessageNamedToolChoiceParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionParam"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageNamedToolChoiceParam"
},
"AssistantMessageEventsDeltaRead": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content_blocks": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TextContentBlock"
},
{
"$ref": "#/components/schemas/ReasoningContentBlock"
},
{
"$ref": "#/components/schemas/ToolCall"
},
{
"$ref": "#/components/schemas/ToolResult"
},
{
"$ref": "#/components/schemas/ServerToolCall"
},
{
"$ref": "#/components/schemas/ServerToolResult"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"reasoning": "#/components/schemas/ReasoningContentBlock",
"server_tool_call": "#/components/schemas/ServerToolCall",
"server_tool_result": "#/components/schemas/ServerToolResult",
"text": "#/components/schemas/TextContentBlock",
"tool_call": "#/components/schemas/ToolCall",
"tool_result": "#/components/schemas/ToolResult"
}
}
},
"type": "array",
"title": "Content Blocks"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
}
},
"type": "object",
"required": [
"content_blocks",
"sources"
],
"title": "AssistantMessageEventsDeltaRead",
"description": "Streaming delta for events streaming where content is a list[ContentBlock]."
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"UserData": {
"properties": {
"licence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Licence"
}
},
"type": "object",
"title": "UserData"
},
"FunctionDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"parameters": {
"additionalProperties": true,
"type": "object",
"title": "Parameters"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
}
},
"type": "object",
"required": [
"name",
"parameters"
],
"title": "FunctionDefinition"
},
"FunctionParam": {
"properties": {
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "FunctionParam"
},
"TextContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "text",
"title": "Type",
"default": "text"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"annotations": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Annotations"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"text"
],
"title": "TextContentBlock",
"description": "Text output. Attributes mirror LangChain's ``TextContentBlock`` (core 1.4.x).\n\nLangChain marks every field except ``text`` as ``NotRequired``, so here they are optional with a\n``None`` default. ``annotations`` stays a loose ``list[dict]`` instead of a copy of LangChain's\n``Annotation`` union, because HAI does not process citations."
},
"ReasoningContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "reasoning",
"title": "Type",
"default": "reasoning"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"title": "ReasoningContentBlock",
"description": "Reasoning output. Mirrors LangChain's ``ReasoningContentBlock`` (core 1.4.x)."
},
"ToolCall": {
"properties": {
"type": {
"type": "string",
"const": "tool_call",
"title": "Type",
"default": "tool_call"
},
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"args": {
"additionalProperties": true,
"type": "object",
"title": "Args"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"name",
"args"
],
"title": "ToolCall",
"description": "Client-side tool call request."
},
"ToolResult": {
"properties": {
"type": {
"type": "string",
"const": "tool_result",
"title": "Type",
"default": "tool_result"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id"
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"default": "success"
},
"output": {
"type": "string",
"title": "Output",
"default": ""
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"tool_call_id"
],
"title": "ToolResult",
"description": "Result of a *client-side* tool call, carried in the ``content_blocks`` of a ``ToolMessage``.\n\nThe caller supplies this block, so a model never emits one.\nLangChain has no client-side tool-result block for that reason: there the result is the ``ToolMessage`` itself.\nHAI needs one because every message role stores its payload as content blocks, and the link to the request\n(``tool_call_id``) needs a carrier.\n\n``output`` is the tool output. It is a ``str`` because a ``str`` is what the API\nreceives, what the model sees, and what the v1 API returns.\n\nIt often holds a JSON-serialized object, which this block does not parse\nParsing also lost data (duplicate keys, escaping, whitespace) and let ``json.loads`` admit ``NaN`` into a\nJSONB-bound column.\n\nA consumer that wants the structure back parses it once it knows which tool produced the output.\n``ServerToolResult.output`` keeps its structure, because there LangChain gives it to us.\n\n``status`` mirrors LangChain's ``ToolMessage.status``: two values, defaulting to ``\"success\"``.\nLangChain keeps it on the message because the message *is* the result there. HAI keeps it on the\nblock, so a tool result carries its own outcome wherever the block travels. The message-level\ncounterpart is ``ToolMessage.status``, which reads it back off this block."
},
"ServerToolCall": {
"properties": {
"type": {
"type": "string",
"const": "server_tool_call",
"title": "Type",
"default": "server_tool_call"
},
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"args": {
"additionalProperties": true,
"type": "object",
"title": "Args"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"name",
"args"
],
"title": "ServerToolCall",
"description": "Server-side / inline tool call executed by the agent within the same turn (e.g. DeepAgent).\n\nMirrors LangChain's ``ServerToolCall``."
},
"ServerToolResult": {
"properties": {
"type": {
"type": "string",
"const": "server_tool_result",
"title": "Type",
"default": "server_tool_result"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id"
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"default": "success"
},
"output": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": true,
"type": "object"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Output"
},
"index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Index"
},
"extras": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Extras"
}
},
"additionalProperties": true,
"type": "object",
"required": [
"tool_call_id"
],
"title": "ServerToolResult",
"description": "Result of a server-side / inline tool call, recorded in the same assistant message.\n\nMirrors LangChain's ``ServerToolResult``, except for ``output``. LangChain types that field\n``Any``, because its block is a cross-provider container. HAI fills it from one place only:\n``DeepAgentEngine._messages_from_tools_node`` assigns a LangChain ``ToolMessage.content`` of\ntype ``str | list[str | dict]``. A single text result, the common MCP case, arrives as a ``str``.\nSeveral parts, or a non-text part, arrive as a list of LangChain content blocks. A bare ``dict``\ncannot occur, so the type excludes it.\n\nUnlike ``ToolResult``, the structure here is given and not guessed, so the block keeps it.\nFlattening would destroy a multimodal result. ``None`` stays allowed, as in LangChain's\n``NotRequired``, so every stored row still reads. The anonymizer walks ``str`` values and nested\n``dict``/``list`` values."
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
}
}
}
```
# Create a run
```json
{
"method": "POST",
"path": "/v1/threads/{thread_id}/run",
"tags": [
"Threads"
],
"summary": "Create a run",
"description": "Invokes the assistant on a thread and returns the response. Accepts optional tool configuration. The thread must contain at least one user message. An assistant message requesting tool calls must be followed by the corresponding tool messages. For every tool message, a corresponding assistant message with the same tool_call_id must exist.",
"operationId": "create_run_new_v1_threads__thread_id__run_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AssistantMessageRead"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"content_filter_error": {
"summary": "Content Filter Error",
"value": {
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_does_not_contain_all_tool_calls": {
"summary": "Thread Does Not Contain All Tool Calls",
"value": {
"error_code": "thread_does_not_contain_all_tool_calls",
"detail": "Thread does not contain all requested tool calls"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_empty": {
"summary": "Thread Empty",
"value": {
"error_code": "thread_empty",
"detail": "The thread is empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_last_message_invalid": {
"summary": "Thread Last Message Invalid",
"value": {
"error_code": "thread_last_message_invalid",
"detail": "Last message in the thread has to be a user, system or tool message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"engine_supports_streaming_only": {
"summary": "Engine Supports Streaming Only",
"value": {
"error_code": "engine_supports_streaming_only",
"detail": "The selected engine supports streaming responses only. Please use the streaming endpoint."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"assistant_is_missing": {
"summary": "Assistant Is Missing",
"value": {
"error_code": "assistant_is_missing",
"detail": "Assistant is missing"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"RunCreate": {
"properties": {
"meta_data": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestMetaData"
},
{
"type": "null"
}
],
"description": "Optional request metadata."
},
"tools": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCallParam"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "Tool definitions the assistant may call."
},
"tool_choice": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"auto",
"required"
]
},
{
"$ref": "#/components/schemas/MessageNamedToolChoiceParam"
},
{
"type": "null"
}
],
"title": "Tool Choice",
"description": "Controls which tool the model calls. Requires tools to be set."
}
},
"type": "object",
"title": "RunCreate",
"examples": [
{},
{
"meta_data": {
"user_data": {
"licence": "PI123"
}
}
},
{
"meta_data": {
"user_data": {
"licence": "PI123"
}
},
"tool_choice": "auto",
"tools": [
{
"function": {
"description": "Search the knowledge base for relevant legal documents.",
"name": "search_documents",
"parameters": {
"properties": {
"query": {
"description": "The search query.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
},
"type": "function"
}
]
}
]
},
"AssistantMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"feedback": {
"anyOf": [
{
"$ref": "#/components/schemas/FeedbackMessageResponse"
},
{
"type": "null"
}
]
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at",
"sources"
],
"title": "AssistantMessageRead",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten.",
"created_at": "2025-03-15T09:13:02.654321Z",
"id": "5e6f7081-9012-def0-1234-556677889900",
"meta_data": {
"intent": "Kündigungsfrist Probezeit",
"legal_advice": false,
"type": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"content": "",
"created_at": "2025-03-15T09:13:05.000000Z",
"id": "6f708192-0123-ef01-2345-667788990011",
"role": "assistant",
"sources": [],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566",
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"RequestMetaData": {
"properties": {
"user_data": {
"anyOf": [
{
"$ref": "#/components/schemas/UserData"
},
{
"type": "null"
}
]
}
},
"type": "object",
"title": "RequestMetaData"
},
"MessageToolCallParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageToolCallParam"
},
"MessageNamedToolChoiceParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionParam"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageNamedToolChoiceParam"
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
},
"FeedbackMessageResponse": {
"properties": {
"feedback": {
"$ref": "#/components/schemas/FeedbackOptions"
},
"negative_feedback_reason_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Negative Feedback Reason Id"
},
"negative_feedback_comment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Negative Feedback Comment"
}
},
"type": "object",
"required": [
"feedback"
],
"title": "FeedbackMessageResponse"
},
"MessageToolCall": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"function": {
"$ref": "#/components/schemas/Function"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"id",
"function",
"type"
],
"title": "MessageToolCall",
"description": "Structure of the tool call in the assistant message.\nThis corresponds to the LLM requesting to execute a tool."
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"UserData": {
"properties": {
"licence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Licence"
}
},
"type": "object",
"title": "UserData"
},
"FunctionDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"parameters": {
"additionalProperties": true,
"type": "object",
"title": "Parameters"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
}
},
"type": "object",
"required": [
"name",
"parameters"
],
"title": "FunctionDefinition"
},
"FunctionParam": {
"properties": {
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "FunctionParam"
},
"FeedbackOptions": {
"type": "string",
"enum": [
"positive",
"negative"
],
"title": "FeedbackOptions"
},
"Function": {
"properties": {
"arguments": {
"type": "string",
"title": "Arguments"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"arguments",
"name"
],
"title": "Function"
}
}
}
```
# Stream a run
```json
{
"method": "POST",
"path": "/v1/threads/{thread_id}/run/stream",
"tags": [
"Threads"
],
"summary": "Stream a run",
"description": "Invokes the assistant on a thread and streams the response as NDJSON. The thread must contain at least one user message and end on a user or tool message. An assistant message requesting tool calls must be followed by the corresponding tool messages. For every tool message, a corresponding assistant message with the same tool_call_id must exist.",
"operationId": "create_run_stream_new_v1_threads__thread_id__run_stream_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageChunkResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"content_filter_error": {
"summary": "Content Filter Error",
"value": {
"error_code": "content_filter_error",
"detail": "Could not parse response content as the request was rejected by the content filter."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_does_not_contain_all_tool_calls": {
"summary": "Thread Does Not Contain All Tool Calls",
"value": {
"error_code": "thread_does_not_contain_all_tool_calls",
"detail": "Thread does not contain all requested tool calls"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_empty": {
"summary": "Thread Empty",
"value": {
"error_code": "thread_empty",
"detail": "The thread is empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_last_message_invalid": {
"summary": "Thread Last Message Invalid",
"value": {
"error_code": "thread_last_message_invalid",
"detail": "Last message in the thread has to be a user, system or tool message"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"assistant_is_missing": {
"summary": "Assistant Is Missing",
"value": {
"error_code": "assistant_is_missing",
"detail": "Assistant is missing"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"engine_does_not_support_streaming": {
"summary": "Engine Does Not Support Streaming",
"value": {
"error_code": "engine_does_not_support_streaming",
"detail": "The selected engine does not support streaming responses. Please use the non-streaming endpoint."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"RunCreate": {
"properties": {
"meta_data": {
"anyOf": [
{
"$ref": "#/components/schemas/RequestMetaData"
},
{
"type": "null"
}
],
"description": "Optional request metadata."
},
"tools": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCallParam"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tools",
"description": "Tool definitions the assistant may call."
},
"tool_choice": {
"anyOf": [
{
"type": "string",
"enum": [
"none",
"auto",
"required"
]
},
{
"$ref": "#/components/schemas/MessageNamedToolChoiceParam"
},
{
"type": "null"
}
],
"title": "Tool Choice",
"description": "Controls which tool the model calls. Requires tools to be set."
}
},
"type": "object",
"title": "RunCreate",
"examples": [
{},
{
"meta_data": {
"user_data": {
"licence": "PI123"
}
}
},
{
"meta_data": {
"user_data": {
"licence": "PI123"
}
},
"tool_choice": "auto",
"tools": [
{
"function": {
"description": "Search the knowledge base for relevant legal documents.",
"name": "search_documents",
"parameters": {
"properties": {
"query": {
"description": "The search query.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
},
"type": "function"
}
]
}
]
},
"MessageChunkResponse": {
"properties": {
"message_id": {
"type": "string",
"format": "uuid",
"title": "Message Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"delta": {
"$ref": "#/components/schemas/MessageDeltaResponse"
}
},
"type": "object",
"required": [
"message_id",
"thread_id",
"created_at",
"delta"
],
"title": "MessageChunkResponse",
"description": "This object is the chunk representation that wraps an AssistantMessageRead during streaming.",
"examples": [
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content": "Während der Probezeit beträgt die Kündigungsfrist ",
"role": "assistant",
"sources": []
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"created_at": "2025-03-15T09:13:02.654321Z",
"delta": {
"content": "gemäß § 622 Abs. 3 BGB zwei Wochen.",
"meta_data": {
"intent": "Kündigungsfrist Probezeit",
"legal_advice": false
},
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit...",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
]
},
"message_id": "5e6f7081-9012-def0-1234-556677889900",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"RequestMetaData": {
"properties": {
"user_data": {
"anyOf": [
{
"$ref": "#/components/schemas/UserData"
},
{
"type": "null"
}
]
}
},
"type": "object",
"title": "RequestMetaData"
},
"MessageToolCallParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionDefinition"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageToolCallParam"
},
"MessageNamedToolChoiceParam": {
"properties": {
"function": {
"$ref": "#/components/schemas/FunctionParam"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"function",
"type"
],
"title": "MessageNamedToolChoiceParam"
},
"MessageDeltaResponse": {
"properties": {
"role": {
"$ref": "#/components/schemas/MessageRoleEnum"
},
"content": {
"type": "string",
"title": "Content"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
},
"tool_calls": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"role",
"content",
"sources"
],
"title": "MessageDeltaResponse",
"description": "This object is the Chunk representation of an AssistantMessageRead during streaming."
},
"UserData": {
"properties": {
"licence": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Licence"
}
},
"type": "object",
"title": "UserData"
},
"FunctionDefinition": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"parameters": {
"additionalProperties": true,
"type": "object",
"title": "Parameters"
},
"strict": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Strict"
}
},
"type": "object",
"required": [
"name",
"parameters"
],
"title": "FunctionDefinition"
},
"FunctionParam": {
"properties": {
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "FunctionParam"
},
"MessageRoleEnum": {
"type": "string",
"enum": [
"user",
"assistant",
"system",
"tool"
],
"title": "MessageRoleEnum"
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
}
}
}
```
# Create a thread
```json
{
"method": "POST",
"path": "/v1/threads",
"tags": [
"Threads"
],
"summary": "Create a thread",
"description": "Creates a new conversation thread for stateful dialogues between an end user and an assistant.",
"operationId": "create_thread_v1_threads_post",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadCreate"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"assistant_not_licensed": {
"summary": "Assistant Not Licensed",
"value": {
"error_code": "assistant_not_licensed",
"detail": "The access token has no licensed product for this assistant"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"user_id_conflicts_with_token": {
"summary": "User Id Conflicts With Token",
"value": {
"error_code": "user_id_conflicts_with_token",
"detail": "The user_id in the request differs from the user of the access token"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
},
"validation_error": {
"summary": "Validation error",
"value": {
"error_code": "validation_error",
"detail": [
{
"loc": [
"body",
"assistant_id"
],
"message": "Field required",
"type": "missing"
}
]
},
"schema": {
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Detail",
"type": "array"
}
},
"required": [
"error_code",
"detail"
],
"title": "CustomRequestValidationErrorSchema",
"type": "object"
}
},
"unprocessable_character": {
"summary": "Unprocessable Character",
"value": {
"error_code": "unprocessable_character",
"detail": "String contains characters that cannot be encoded in UTF-8."
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
},
{
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Detail",
"type": "array"
}
},
"required": [
"error_code",
"detail"
],
"title": "CustomRequestValidationErrorSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ThreadCreate": {
"properties": {
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id",
"description": "The assistant this thread is assigned to. Must belong to the tenant."
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id",
"description": "Optional end-user ID in your system."
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title",
"description": "Optional human-readable thread title. Defaults to a timestamp-based name if omitted."
}
},
"type": "object",
"required": [
"assistant_id"
],
"title": "ThreadCreate",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"title": "Fragen zur Elternzeit",
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab"
}
]
},
"ThreadResponse": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"title": "Tenant Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id"
},
"title": {
"type": "string",
"title": "Title"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
}
},
"type": "object",
"required": [
"id",
"tenant_id",
"assistant_id",
"title",
"created_at"
],
"title": "ThreadResponse",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-15T09:12:33.456789Z",
"id": "1a2b3c4d-5678-9abc-def0-112233445566",
"last_updated_at": "2025-03-15T09:45:12.123456Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Kündigung während der Probezeit",
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-14T14:22:10.654321Z",
"id": "2b3c4d5e-6789-abcd-ef01-223344556677",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Elternzeit beantragen"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-10T08:00:00.000000Z",
"deleted_at": "2025-03-12T16:30:00.000000Z",
"id": "3c4d5e6f-7890-bcde-f012-334455667788",
"last_updated_at": "2025-03-10T08:05:30.000000Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Urlaubsanspruch bei Teilzeit"
}
]
}
}
}
```
# Delete a message
```json
{
"method": "DELETE",
"path": "/v1/threads/{thread_id}/messages/{message_id}",
"tags": [
"Threads"
],
"summary": "Delete a message",
"description": "Deletes a single message from a thread.",
"operationId": "delete_message_new_v1_threads__thread_id__messages__message_id__delete",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
},
{
"name": "message_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Message Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"message_not_found": {
"summary": "Message Not Found",
"value": {
"error_code": "message_not_found",
"detail": "Message not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
```
# Delete a thread
```json
{
"method": "DELETE",
"path": "/v1/threads/{thread_id}",
"tags": [
"Threads"
],
"summary": "Delete a thread",
"description": "Soft-deletes a thread and schedules redaction of the content of all its messages.",
"operationId": "delete_thread_v1_threads__thread_id__delete",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
```
# List messages
```json
{
"method": "GET",
"path": "/v1/threads/{thread_id}/messages",
"tags": [
"Threads"
],
"summary": "List messages",
"description": "Returns a paginated list of messages for a thread, ordered by creation date descending. Supports cursor-based pagination.",
"operationId": "get_all_messages_new_v1_threads__thread_id__messages_get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 100,
"title": "Limit"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cursor string",
"title": "Cursor"
},
"description": "Cursor string"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageResponseCursorPage"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"assistant_not_found": {
"summary": "Assistant Not Found",
"value": {
"error_code": "assistant_not_found",
"detail": "Assistant not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"MessageResponseCursorPage": {
"properties": {
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor",
"description": "Cursor string"
},
"items": {
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/HumanMessageRead"
},
{
"$ref": "#/components/schemas/SystemMessageRead"
},
{
"$ref": "#/components/schemas/ToolMessageRead"
},
{
"$ref": "#/components/schemas/AssistantMessageRead"
}
],
"discriminator": {
"propertyName": "role",
"mapping": {
"assistant": "#/components/schemas/AssistantMessageRead",
"system": "#/components/schemas/SystemMessageRead",
"tool": "#/components/schemas/ToolMessageRead",
"user": "#/components/schemas/HumanMessageRead"
}
}
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "MessageResponseCursorPage"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"HumanMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "user",
"title": "Role",
"default": "user"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/AttachmentRead"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at"
],
"title": "HumanMessageRead",
"examples": [
{
"content": "Welche Kündigungsfristen gelten während der Probezeit?",
"created_at": "2025-03-15T09:12:45.123456Z",
"id": "4d5e6f70-8901-cdef-0123-445566778899",
"role": "user",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"SystemMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "system",
"title": "Role",
"default": "system"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at"
],
"title": "SystemMessageRead",
"examples": [
{
"content": "Du bist ein Experte für deutsches Arbeitsrecht. Antworte stets auf Deutsch und verweise auf relevante Gesetzesgrundlagen.",
"created_at": "2025-03-15T09:12:33.456789Z",
"id": "7a8b9c0d-1234-abcd-ef01-778899001122",
"role": "system",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
}
]
},
"ToolMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "tool",
"title": "Role",
"default": "tool"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"tool_call_id": {
"type": "string",
"title": "Tool Call Id"
},
"status": {
"type": "string",
"enum": [
"success",
"error"
],
"title": "Status",
"description": "The state of the tool run.",
"default": "success"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at",
"tool_call_id"
],
"title": "ToolMessageRead",
"examples": [
{
"content": "{\"results\": [{\"title\": \"§ 622 BGB Kündigungsfristen\", \"snippet\": \"Während einer vereinbarten Probezeit kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.\"}]}",
"created_at": "2025-03-15T09:13:06.000000Z",
"id": "8b9c0d1e-2345-bcde-f012-889900112233",
"role": "tool",
"status": "success",
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566",
"tool_call_id": "call_abc123"
}
]
},
"AssistantMessageRead": {
"properties": {
"role": {
"type": "string",
"const": "assistant",
"title": "Role",
"default": "assistant"
},
"content": {
"type": "string",
"title": "Content"
},
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"thread_id": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"sources": {
"items": {
"$ref": "#/components/schemas/SourceSchema"
},
"type": "array",
"title": "Sources"
},
"feedback": {
"anyOf": [
{
"$ref": "#/components/schemas/FeedbackMessageResponse"
},
{
"type": "null"
}
]
},
"tool_calls": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/MessageToolCall"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tool Calls"
},
"meta_data": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Meta Data"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"content",
"id",
"thread_id",
"created_at",
"sources"
],
"title": "AssistantMessageRead",
"examples": [
{
"content": "Während der Probezeit beträgt die Kündigungsfrist gemäß § 622 Abs. 3 BGB zwei Wochen. Diese Frist gilt für beide Seiten.",
"created_at": "2025-03-15T09:13:02.654321Z",
"id": "5e6f7081-9012-def0-1234-556677889900",
"meta_data": {
"intent": "Kündigungsfrist Probezeit",
"legal_advice": false,
"type": "53aa66b7-b874-407f-967c-3a959c919d62"
},
"role": "assistant",
"sources": [
{
"content": "§ 622 Abs. 3 BGB: Während einer vereinbarten Probezeit, längstens für die Dauer von sechs Monaten, kann das Arbeitsverhältnis mit einer Frist von zwei Wochen gekündigt werden.",
"meta_data": {
"document_title": "Bürgerliches Gesetzbuch (BGB)",
"section": "§ 622 Abs. 3"
}
}
],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566"
},
{
"content": "",
"created_at": "2025-03-15T09:13:05.000000Z",
"id": "6f708192-0123-ef01-2345-667788990011",
"role": "assistant",
"sources": [],
"thread_id": "1a2b3c4d-5678-9abc-def0-112233445566",
"tool_calls": [
{
"function": {
"arguments": "{\"query\": \"Probezeit Kündigung\"}",
"name": "search_documents"
},
"id": "call_abc123",
"type": "function"
}
]
}
]
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"AttachmentRead": {
"properties": {
"file_id": {
"type": "string",
"format": "uuid",
"title": "File Id"
}
},
"type": "object",
"required": [
"file_id"
],
"title": "AttachmentRead",
"description": "Response object for the attachment endpoint.\n\nWe do not expose the content for payload size reasons."
},
"SourceSchema": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "Content of the source object"
},
"meta_data": {
"additionalProperties": true,
"type": "object",
"title": "Meta Data",
"description": "Metadata associated with the source object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"meta_data"
],
"title": "SourceSchema"
},
"FeedbackMessageResponse": {
"properties": {
"feedback": {
"$ref": "#/components/schemas/FeedbackOptions"
},
"negative_feedback_reason_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Negative Feedback Reason Id"
},
"negative_feedback_comment": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Negative Feedback Comment"
}
},
"type": "object",
"required": [
"feedback"
],
"title": "FeedbackMessageResponse"
},
"MessageToolCall": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"function": {
"$ref": "#/components/schemas/Function"
},
"type": {
"type": "string",
"const": "function",
"title": "Type"
}
},
"type": "object",
"required": [
"id",
"function",
"type"
],
"title": "MessageToolCall",
"description": "Structure of the tool call in the assistant message.\nThis corresponds to the LLM requesting to execute a tool."
},
"FeedbackOptions": {
"type": "string",
"enum": [
"positive",
"negative"
],
"title": "FeedbackOptions"
},
"Function": {
"properties": {
"arguments": {
"type": "string",
"title": "Arguments"
},
"name": {
"type": "string",
"title": "Name"
}
},
"type": "object",
"required": [
"arguments",
"name"
],
"title": "Function"
}
}
}
```
# List threads
```json
{
"method": "GET",
"path": "/v1/threads",
"tags": [
"Threads"
],
"summary": "List threads",
"description": "Returns a paginated list of threads for the current tenant. Supports cursor-based pagination and filtering by user ID.",
"operationId": "get_all_threads_v1_threads_get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 100,
"title": "Limit"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cursor string",
"title": "Cursor"
},
"description": "Cursor string"
},
{
"name": "user_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
{
"name": "include_deleted",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Include Deleted"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadResponseCursorPage"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ThreadResponseCursorPage": {
"properties": {
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor",
"description": "Cursor string"
},
"items": {
"items": {
"$ref": "#/components/schemas/ThreadResponse"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "ThreadResponseCursorPage"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ThreadResponse": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"title": "Tenant Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id"
},
"title": {
"type": "string",
"title": "Title"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
}
},
"type": "object",
"required": [
"id",
"tenant_id",
"assistant_id",
"title",
"created_at"
],
"title": "ThreadResponse",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-15T09:12:33.456789Z",
"id": "1a2b3c4d-5678-9abc-def0-112233445566",
"last_updated_at": "2025-03-15T09:45:12.123456Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Kündigung während der Probezeit",
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-14T14:22:10.654321Z",
"id": "2b3c4d5e-6789-abcd-ef01-223344556677",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Elternzeit beantragen"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-10T08:00:00.000000Z",
"deleted_at": "2025-03-12T16:30:00.000000Z",
"id": "3c4d5e6f-7890-bcde-f012-334455667788",
"last_updated_at": "2025-03-10T08:05:30.000000Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Urlaubsanspruch bei Teilzeit"
}
]
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
```
# Get a thread
```json
{
"method": "GET",
"path": "/v1/threads/{thread_id}",
"tags": [
"Threads"
],
"summary": "Get a thread",
"description": "Returns the properties of a single thread by ID.",
"operationId": "get_thread_by_id_v1_threads__thread_id__get",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ThreadResponse": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"title": "Tenant Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id"
},
"title": {
"type": "string",
"title": "Title"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
}
},
"type": "object",
"required": [
"id",
"tenant_id",
"assistant_id",
"title",
"created_at"
],
"title": "ThreadResponse",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-15T09:12:33.456789Z",
"id": "1a2b3c4d-5678-9abc-def0-112233445566",
"last_updated_at": "2025-03-15T09:45:12.123456Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Kündigung während der Probezeit",
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-14T14:22:10.654321Z",
"id": "2b3c4d5e-6789-abcd-ef01-223344556677",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Elternzeit beantragen"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-10T08:00:00.000000Z",
"deleted_at": "2025-03-12T16:30:00.000000Z",
"id": "3c4d5e6f-7890-bcde-f012-334455667788",
"last_updated_at": "2025-03-10T08:05:30.000000Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Urlaubsanspruch bei Teilzeit"
}
]
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
}
}
}
```
# Update a thread
```json
{
"method": "PATCH",
"path": "/v1/threads/{thread_id}",
"tags": [
"Threads"
],
"summary": "Update a thread",
"description": "Updates mutable properties of a thread such as its title.",
"operationId": "update_thread_v1_threads__thread_id__patch",
"security": [
{
"APIKeyHeader": []
},
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "thread_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Thread Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ThreadResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"thread_is_deactivated": {
"summary": "Thread Is Deactivated",
"value": {
"error_code": "thread_is_deactivated",
"detail": "Thread is deactivated"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"examples": {
"unauthorized": {
"summary": "Unauthorized",
"value": {
"error_code": "unauthorized",
"detail": "Missing or invalid API key"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"thread_not_found": {
"summary": "Thread Not Found",
"value": {
"error_code": "thread_not_found",
"detail": "Thread not found"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"thread_title_empty": {
"summary": "Thread Title Empty",
"value": {
"error_code": "thread_title_empty",
"detail": "Title cannot not be empty"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"examples": {
"rate_limit_exceeded_seconds": {
"summary": "Rate limit exceeded! You reached the limit of 6 requests per second.",
"value": {
"message": "Rate limit exceeded!"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
},
"rate_limit_exceeded_minutes": {
"summary": "rate limit per minute",
"value": {
"message": "Rate limit exceeded! You've reached the limit of 60 requests per 1 minutes"
},
"schema": {
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"properties": {
"message": {
"title": "Message",
"type": "string"
}
},
"required": [
"message"
],
"title": "GraviteeExceptionSchema",
"type": "object"
}
]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "Internal Server Error",
"value": {
"error_code": "internal_server_error",
"detail": "Internal Server Error"
},
"schema": {
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
}
},
"schema": {
"oneOf": [
{
"description": "Schema of the ServiceExceptions",
"properties": {
"error_code": {
"title": "Error Code",
"type": "string"
},
"detail": {
"title": "Detail",
"type": "string"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
}
},
"required": [
"error_code",
"detail",
"headers"
],
"title": "ServiceExceptionSchema",
"type": "object"
}
]
}
}
}
}
},
"schemas": {
"ThreadUpdate": {
"properties": {
"title": {
"type": "string",
"title": "Title",
"description": "New thread title. Must not be empty."
}
},
"type": "object",
"required": [
"title"
],
"title": "ThreadUpdate",
"examples": [
{
"title": "Kündigung während Probezeit - Fristen"
},
{
"title": "Urlaubsanspruch bei Teilzeitarbeit"
}
]
},
"ThreadResponse": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"title": "Tenant Id"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
},
"assistant_id": {
"type": "string",
"format": "uuid",
"title": "Assistant Id"
},
"title": {
"type": "string",
"title": "Title"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"last_updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Updated At"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Deleted At"
}
},
"type": "object",
"required": [
"id",
"tenant_id",
"assistant_id",
"title",
"created_at"
],
"title": "ThreadResponse",
"examples": [
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-15T09:12:33.456789Z",
"id": "1a2b3c4d-5678-9abc-def0-112233445566",
"last_updated_at": "2025-03-15T09:45:12.123456Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Kündigung während der Probezeit",
"user_id": "f8e7d6c5-4321-fedc-ba98-765432109876"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-14T14:22:10.654321Z",
"id": "2b3c4d5e-6789-abcd-ef01-223344556677",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Elternzeit beantragen"
},
{
"assistant_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
"created_at": "2025-03-10T08:00:00.000000Z",
"deleted_at": "2025-03-12T16:30:00.000000Z",
"id": "3c4d5e6f-7890-bcde-f012-334455667788",
"last_updated_at": "2025-03-10T08:05:30.000000Z",
"tenant_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"title": "Urlaubsanspruch bei Teilzeit"
}
]
}
}
}
```