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
Quick Reference

Here are the main API endpoints grouped by function. For full details, use the OpenAPI documentation.

Files

Upload, list, and manage documents in your organization.

GET/files
POST/files
DELETE/files/{id}
GET/files/{id}/chunks
POST/files/{id}/reprocess

Conversations

Ask questions and manage conversation history.

POST/conversations/ask
GET/conversations
GET/conversations/{id}
DELETE/conversations/{id}

Agents

Create and manage custom AI agents.

GET/agents
POST/agents
PATCH/agents/{id}
DELETE/agents/{id}

Organizations

Manage organizations and team members.

GET/organizations
POST/organizations
GET/organizations/members
POST/organizations/members
PATCH/organizations/members/{id}/role
DELETE/organizations/members/{id}

API Keys

Create and manage API access keys.

GET/api-keys
POST/api-keys
DELETE/api-keys/{id}

Tools

Configure agent tools and capabilities.

GET/tools
PATCH/tools
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

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",
}

# 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
    )
    print(response.json())

Ask a question:

import requests

response = requests.post(
    "https://cloud.yeos.ai/api/conversations/ask",
    headers={
        "Authorization": "Bearer yeos_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "question": "What is the refund policy?",
        "organization_id": "your_org_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 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/conversations/ask',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer yeos_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      question: 'What is the refund policy?',
      organization_id: 'your_org_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 /conversations/stream endpoint for 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.