API Overview

The Evose API is the entry point for external systems calling Evose. It lets you embed Agents / Workflows / knowledge bases into your own systems.

Design Principles

• REST: clear resources / verbs
• JSON: both request and response bodies are JSON
• HTTPS required: all requests over TLS
• Idempotent: identical requests yield the same result (writes support Idempotency-Key)
• Versioned: major version in the URL (/v1/...)
• Observable: every response includes a request_id for troubleshooting

Base URL

Resource Endpoints

A Minimal Example

curl -X POST https://api.evose.ai/v1/agents/agent-12345/chat \
  -H "Authorization: Bearer evk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "hello",
    "user_id": "u-001",
    "stream": false
  }'

Response:

{
  "request_id": "req-abc123",
  "agent_id": "agent-12345",
  "conversation_id": "conv-xyz",
  "message": {
    "role": "assistant",
    "content": "Hi! What can I help you with?"
  },
  "usage": {
    "tokens_in": 8,
    "tokens_out": 12,
    "credits": 0.001
  }
}

SDKs (Planned)

For now, call HTTPS directly.

Next Steps

• Authentication
• Conventions
• Errors
• Rate limits