Documentation

yeos documentation.

REST API

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/api

Authentication

All API requests require an API key. Include your key in the Authorization header as a Bearer token.

Authorization: Bearer yeos_your_api_key

Interactive Documentation

For the complete API reference with request/response schemas, examples, and interactive testing, visit our OpenAPI documentation.

View Interactive Docs
Permissions (Scopes)

Available Domains

API keys can be restricted to specific permissions. Use scopes to limit what each key can do.

Format: domain:action

Available 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 conversations
documents:writedocuments:write – Upload documents
organization:adminorganization:admin – Full organization control
members:adminmembers:admin – Manage workspace members

Code 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);
LIMITS AND OVERAGE

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.