Documentation
yeos documentation.
API Reference
The yeos API lets you integrate document intelligence into your own applications. All API endpoints are REST-based and return JSON responses.
Base URL
https://cloud.yeos.ai/apiAuthentication
All API requests require an API key. Include your key in the Authorization header as a Bearer token.
Authorization: Bearer yeos_your_api_keyInteractive Documentation
For the complete API reference with request/response schemas, examples, and interactive testing, visit our OpenAPI documentation.
View Interactive DocsAvailable Domains
API keys can be restricted to specific permissions. Use scopes to limit what each key can do.
Format: domain:actionAvailable Domains
conversations – Conversation access
documents – File and document access
members – Team member management
organization – Organization settings
api-keys – API key management
billing – Billing operations
Available Actions
read – View and list resources
write – Create and modify resources
delete – Remove resources
admin – Administrative operations
Example Scopes
conversations:readconversations:read – Read conversationsdocuments:writedocuments:write – Upload documentsorganization:adminorganization:admin – Full organization controlmembers:adminmembers:admin – Manage workspace membersCode Examples
Quick examples to get you started with the API.
Python
pip install requests
Upload a file:
import requests
headers = {
"Authorization": "Bearer yeos_your_api_key",
}
data = {
"organization_id": "your_org_id",
# Optional: include to upload into a workspace.
"workspace_id": "your_workspace_id",
}
# Upload a file
with open("document.pdf", "rb") as f:
files = {"file": f}
response = requests.post(
"https://cloud.yeos.ai/api/files",
headers=headers,
files=files,
data=data,
)
print(response.json())Ask a question:
import requests
response = requests.post(
"https://cloud.yeos.ai/api/chat/completions",
headers={
"Authorization": "Bearer yeos_your_api_key",
"Content-Type": "application/json",
},
json={
"model": "gpt-4",
"stream": False,
"messages": [
{"role": "user", "content": "What is the refund policy?"}
],
"organization_id": "your_org_id",
"workspace_id": "your_workspace_id",
},
)
print(response.json())JavaScript / Node.js
npm install node-fetch
Upload a file:
const fetch = require('node-fetch');
const FormData = require('form-data');
const fs = require('fs');
const workspaceId = 'your_workspace_id';
const formData = new FormData();
const fileStream = fs.createReadStream('document.pdf');
formData.append('file', fileStream);
formData.append('organization_id', 'your_org_id');
formData.append('workspace_id', workspaceId);
const response = await fetch('https://cloud.yeos.ai/api/files', {
method: 'POST',
headers: {
'Authorization': 'Bearer yeos_your_api_key',
},
body: formData,
});
const data = await response.json();
console.log(data);Ask a question:
const response = await fetch(
'https://cloud.yeos.ai/api/chat/completions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer yeos_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gpt-4',
stream: false,
messages: [
{ role: 'user', content: 'What is the refund policy?' },
],
organization_id: 'your_org_id',
workspace_id: 'your_workspace_id',
}),
}
);
const data = await response.json();
console.log(data);Daily message limits
Every plan includes a daily message allowance. Requests beyond it are rejected with HTTP 402 unless your organization has enabled paid API overage.
What a 402 means
limit_reached – the included daily allowance is used up and paid overage is not enabled. Retry after the allowance resets, or enable overage.
payment_required – overage is enabled but no payable subscription is on file. Check your billing details.
overage_cap_exceeded – the spend cap for this billing period has been reached. An admin can raise it in organization settings.
Paid overage
An organization admin can enable paid API overage under Organization settings, Subscription. API key traffic then continues past the daily allowance and is billed by measured token usage. Requests made from the web app always stop at the included limit.
Overage is charged per token: CHF 0.60 per million input tokens and CHF 2.25 per million output tokens.
Spend cap
Overage is bounded by a per-period spend cap, so an enabled organization can never run up an unlimited bill. Admins can adjust it, and current usage against the cap is shown in organization settings.
Tracking usage
Chat completion responses include an OpenAI-compatible usage object with prompt, completion and total token counts, so you can attribute cost per request.
Overage appears on your next invoice alongside your plan fee, as separate line items in a single charge. A period is billed after it ends.
The Free plan has full API access but cannot enable paid overage; it always stops at its included daily allowance.
Common Questions
How do I get an API key?
API keys are created in your organization settings. Only organization owners and admins can create and manage API keys.
What is the rate limit?
Rate limits depend on your plan. The Free plan has basic limits, while paid plans offer higher rate limits for production use.
Can I use the API without an organization?
No. All API requests are scoped to an organization. You need to create an organization first.
Are API responses streamed?
Yes. Question answering supports server-sent events (SSE) for streaming responses. Check the OpenAPI documentation for the current streaming endpoint details.
How do I handle errors?
The API returns standard HTTP status codes. 4xx errors indicate client issues (bad request, unauthorized), while 5xx errors indicate server issues. Check the response body for error details.