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);

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.