# Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.guayaba.run/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Introduction Your agentic infrastructure layer. All your agents, unified. Guayaba is the infrastructure layer for AI agents. Configure your agent through a guided interface — Guayaba handles provisioning, scaling, monitoring, and uptime. **What you can do** * Deploy agents powered by production-grade frameworks * Configure identity, personality, knowledge base, and LLM — no code required * Connect agents to communication channels * Monitor health, logs, and usage in real time * Extend agents with verified plugins from the marketplace ***
# Getting Started ## Create your first agent **\~5 minutes. Result:** a running agent connected to Telegram. ### Before you start You need credits before deploying. Go to **Profile → Buy AI Credits** and purchase a pack. *** {% stepper %} {% step %} ### Infrastructure Click **Create Agent** in the sidebar. **Deployment Region** — choose the region closest to your users. | Region | Location | | ------------ | ----------- | | US West | Oregon | | US East | N. Virginia | | EU West | Dublin | | EU Central | Frankfurt | | Asia Pacific | Singapore | **Hardware Resources** — defaults work for most agents. | Resource | Default | | ------------ | -------- | | CPU | 0.5 Core | | Disk Storage | 5 GB | | Memory (RAM) | 4 GB | | GPU | None | > Higher tiers coming soon. Click **Continue**. {% endstep %} {% step %} ### Framework Select the **framework you want to use.** Click **Continue**. {% endstep %} {% step %} ### Agent Configuration #### Identity | Field | Required | Notes | | ----- | -------- | ------------------------------------ | | Name | ✅ | Display name | | Bio | ✅ | Purpose and identity (max 500 chars) | #### Personality **Additional Instructions** — system-level directives appended after core config. ``` Always cite sources when sharing facts. Never use informal language with users. ``` **Seed Knowledge** — upload PDF or TXT files to inject into long-term memory on first boot. #### Model **Thinking Level** | Level | Best for | | ------ | ------------------ | | Off | Simple Q\&A | | Low | General assistants | | Medium | Most use cases | | High | Complex tasks | **Included Capabilities — always active** | Capability | Description | | ------------------- | ----------------------------------- | | Web Search | Real-time web search | | Web Fetch | Read content from any URL | | Image Understanding | Analyze images from users | | File Access | Read/write files in agent workspace | #### Communication Channels Enable **Telegram** and paste your bot token. > Need a token? See [Telegram](#telegram). #### Review Review full configuration and click **Create Agent**. {% endstep %} {% endstepper %} *** ### Your agent is running Status: **Pending** → **Running** | Action | Description | | ------ | -------------------------------- | | Logs | Real-time runtime activity | | Files | Files in the agent's workspace | | Edit | Modify configuration at any time | | Stop | Pause the agent and free compute | # Platform ## Dashboard | Metric | Description | | ------------------ | ----------------------------------- | | $ Balance | Current monetary balance | | Total uptime | Cumulative uptime across all agents | | Created Agents | Total agents in your account | | AI Credits Balance | Available credits | **Running Agents** — lists every agent in Running state. Empty means no agents are active. *** ## Credits Credits power LLM usage and compute. ### Buying credits Go to **Profile → Buy AI Credits with USDC**. | Pack | Credits | Price | | -------- | ------- | -------- | | Starter | 10,000 | 10 USDC | | Standard | 50,000 | 45 USDC | | Pro | 120,000 | 100 USDC | > Balance always visible top-right of the console. ### What consumes credits **LLM usage** — every message processed. More capable models cost more per interaction. **Compute** — consumed while agent is in Running state. Stops when agent is stopped. ### Monitoring usage From **Agent data → Model section**: | Field | Description | | ----------- | --------------------------------------- | | Total spend | Cumulative cost for this agent | | Spend limit | Configurable cap (Unlimited by default) | | Rate limit | Max requests per time window | *** ## Profile | Field | Description | | ----------- | -------------------------------- | | Public name | Display name across the platform | | Email | Account email | **Wallet Settings** — connect an EVM-compatible wallet to purchase credits with USDC. *** ## Agent Identity Layer > Coming soon. Every agent will receive a cryptographic identity — verifiable, tamper-proof, and portable. | Feature | Description | | ---------------------- | ------------------------------------------------------------------------------------- | | Cryptographic Identity | Unique Ed25519 keypair per agent. Every action is signed and tamper-proof. | | On-Chain Anchoring | Identity hash anchored to blockchain. Public verification. Portable across platforms. | | Agent-to-Agent Auth | Agents prove authorship and verify messages. No spoofing. | *** ## Agentic Payments > Coming soon. Agents will make and receive payments autonomously under programmable constraints you define. ``` Agent A → calls Agent B Agent B → charges 0.01 USDC Policy → validates Payment → settles in < 1s ``` | Control | Description | | ----------------------- | ----------------------------------------------------------------------------- | | Delegated Authority | Spending limits, approved recipients, policy rules — agents can't exceed them | | Agent-to-Agent Commerce | Agents charge per execution and purchase capabilities programmatically | | Enterprise Control | Budget caps, manual approval thresholds, full audit trail | *** # Agents ### Overview | Component | Description | | ----------- | ------------------------------- | | Identity | Name, bio, and purpose | | Personality | Instructions and seed knowledge | | Model | LLM and thinking depth | | Channels | Where users interact with it | | Resources | Compute profile | **Agent states** | State | Meaning | | ------- | ----------------------------------- | | Stopped | Not running. No compute consumed. | | Pending | Provisioning. Usually < 30 seconds. | | Running | Live and accepting messages. | ### Manage **Start** — click **Run Agent** from Agent data. Status: Pending → Running. **Stop** — click **Stop**. Config, files, and memory preserved. Compute stops. **Edit** — click **Edit** at any time. > Changes to model or channels may require a restart. | Status | Available actions | | ------- | ----------------- | | Stopped | Run Agent, Edit | | Pending | — | | Running | Stop, Edit | ### Logs ``` [INFO] Agent runtime booting... [INFO] Loading character configuration... [INFO] Connecting to Telegram channel... [INFO] Agent is now running ``` | Level | Meaning | | ----- | --------------------------------- | | INFO | Normal operational events | | WARN | Non-critical issues | | ERROR | Failures affecting agent behavior | # Frameworks ## OpenClaw Modular agent runtime with built-in memory, tools, and multi-channel support. ### Configuration reference **Identity** | Field | Required | Notes | | ----- | -------- | ------------- | | Name | ✅ | Display name | | Bio | ✅ | Max 500 chars | **Personality** | Field | Description | | ----------------------- | ------------------------------------------------ | | Additional Instructions | System directives appended after core config | | Seed Knowledge | PDF/TXT files injected into memory at first boot | **Thinking Level** | Level | Behavior | | ------ | -------------------------------- | | Off | Single-pass — fastest | | Low | Light planning | | Medium | Moderate reasoning (recommended) | | High | Deep reasoning | **Included Capabilities** | Capability | Description | | ------------------- | ----------------------------- | | Web Search | Real-time web search | | Web Fetch | Read content from any URL | | Image Understanding | Analyze images from users | | File Access | Read/write files in workspace | ### Built-in tools **System** | Tool | Description | | ---------------- | ----------------------------------- | | `character-cfg` | Agent's core configuration | | `agents` | Lists all agents in workspace | | `knowledge-base` | Injects knowledge base into context | | `SCULPT_TO` | Formats output to structured lists | **Agent-managed** | Tool | Description | | -------------- | ------------------------------- | | `MEMORIZE` | Store in long-term memory | | `THINKING` | Internal reasoning step | | `CONSULT_AI` | Delegate to sub-process | | `TOOL_CALL` | Interact with external entities | | `MULTITASK` | Run parallel tasks | | `PLAN_ACTIONS` | Update action queue | | `memory` | Read from memory store | # Channels ## Telegram Connect your agent to Telegram via a bot you control. ### Create a bot 1. Open Telegram → search `@botfather` 2. Send `/newbot` 3. Follow prompts and copy the API token (`1234567890:ABCdef...`) ### Configure in Guayaba 1. Go to **Communication Channels → Telegram** toggle 2. Paste bot token → **Save Settings** 3. Channel shows **✓ Configured** ### User access Users who message your bot receive a **pairing code**. Approve or reject from the Telegram settings panel. > Pairing management requires the agent to be Running. | Section | Description | | ---------------- | ------------------------------------- | | Pairing requests | Pending approvals | | Approved users | Active users. Click Revoke to remove. | **Channel status** | Status | Meaning | | ---------- | --------------------------------- | | Configured | Token saved, ready to go live | | Active | Agent running, accepting messages | | Inactive | Agent stopped | # FAQ ## FAQ
What is Guayaba? Infrastructure platform for AI agents. Deploy and manage agents in production without code or servers.
Do I need technical experience? No. The dashboard guides you through every step.
How do I sign up? Go to guayaba.run — log in with email or a Web3 wallet, either works.
Can I run multiple agents? Yes. Each runs in its own isolated container.
What happens when I stop an agent? Config, files, and memory are preserved. Compute stops. Restart anytime.
Can I edit a running agent? Yes. Some changes require a restart to take effect.
What is OpenClaw? The first framework on Guayaba — modular agent runtime with built-in tools, memory, and multi-channel support.
Will more frameworks be added? Yes, based on community demand.
# API Introduction The Guayaba Public API lets you create, manage, and chat with your AI agents programmatically — no web UI needed. ### Base URL ``` https://api.guayaba.run/api/v1 ``` All endpoints are relative to this base URL. ### Quick Start #### 1. Create an API key Go to **Settings → API Keys** in the [Guayaba dashboard](https://app.guayaba.run/) and create a **Master Key**. #### 2. List your agents ``` curl https://api.guayaba.run/api/v1/agents \ -H "Authorization: Bearer g_master_YOUR_KEY" ``` #### 3. Start an agent ``` curl -X POST https://api.guayaba.run/api/v1/agents/{id}/start \ -H "Authorization: Bearer g_master_YOUR_KEY" ``` #### 4. Chat with your agent ``` curl -X POST https://api.guayaba.run/api/v1/agents/{id}/chat \ -H "Authorization: Bearer g_master_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Hello, what can you do?"}' ``` ### Requirements * An active Guayaba subscription (any tier). * At least one API key (Master or Agent). * Sufficient credits for billed operations. # Authentication All API requests require an API key sent as a **Bearer token**: ``` Authorization: Bearer ``` ### Key Types Guayaba uses a two-tier key system: #### Master Key (`g_master_`) * **One per user.** Creating a new one revokes the previous master key and all its agent keys. * Full access to every endpoint and every agent you own. * Required for: creating/updating/deleting agents, billing endpoints, and managing API keys. * Format: `g_master_` + 48 hex characters (57 chars total). #### Agent Key (`g_agent_`) * **One per agent.** Tied to a single agent by ID. * Limited access controlled by **scopes** you choose at creation time. * Cannot access other agents — returns `403` if attempted. * Format: `g_agent_` + 48 hex characters (56 chars total). ### Creating Keys Keys are managed from the Guayaba dashboard: * **Master Key**: Settings → API Keys → Create Master Key * **Agent Key**: Agent Detail → API Keys → Create Agent Key > **You must have an active master key before creating agent keys.** If your master key is revoked, you need to create a new one first. > The full key is shown **only once** at creation. Store it securely — lost keys cannot be recovered, only regenerated. ### Scopes Scopes control what an agent key can do. Master keys bypass all scope checks. | Scope | Description | Included by default | | -------------- | -------------------------------------------------------- | ------------------- | | `agent:read` | View agent details and configuration | Always | | `agent:manage` | Start, stop, pause, reload. Manage sessions and archives | No | | `channels` | Manage Telegram pairing (list, approve, revoke, reject) | No | | `files` | Upload files to the agent | No | | `chat` | Send messages to the agent via API | No | `agent:read` is always included automatically in every agent key. ### Subscription Requirement All endpoints require the key owner to have an **active subscription** (status: `active` or `trialing`). If the subscription is inactive, every request returns: ``` 403 Forbidden { "error": "Forbidden", "message": "An active subscription is required to use the API" } ``` ### Key Revocation * **Revoking a master key cascades** — all agent keys under that user are also revoked. * Regenerating a key revokes the old one and creates a new one. * Revoked keys return `401 Unauthorized` immediately. ### Key Expiration Keys can optionally be set to expire at a specific date. By default, keys do not expire. Expired keys behave the same as revoked keys (`401`). ### Example ``` # Using a master key curl https://api.guayaba.run/api/v1/agents \ -H "Authorization: Bearer g_master_a1b2c3d4e5f6..." # Using an agent key (with agent:read scope) curl https://api.guayaba.run/api/v1/agents/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer g_agent_f6e5d4c3b2a1..." ``` # Agents ## List Agents Returns all agents owned by the API key's user. ``` GET /agents ``` **Auth**: Any key (master or agent). **Query parameters**: | Parameter | Type | Default | Description | | ---------- | ------- | ------- | ---------------- | | `per_page` | integer | 100 | Results per page | | `page` | integer | 1 | Page number | ``` curl https://api.guayaba.run/api/v1/agents \ -H "Authorization: Bearer g_master_YOUR_KEY" ``` **Response** (`200`): ``` { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "My Agent", "status": "running", "channels": ["telegram"], "model_provider": "openrouter", "settings": { "model": "openai/gpt-4.1" }, "created_at": "2026-03-15T10:30:00Z" } ], "current_page": 1, "last_page": 1, "per_page": 100, "total": 1 } ``` *** ### Show Agent Returns full details for a specific agent. ``` GET /agents/{id} ``` **Auth**: Master key (any agent) or agent key with `agent:read` scope (own agent only). ``` curl https://api.guayaba.run/api/v1/agents/550e8400-... \ -H "Authorization: Bearer g_agent_YOUR_KEY" ``` *** ### Create Agent Creates a new AI agent. ``` POST /agents ``` **Auth**: Master key only. **Cost**: 10 credits. ``` curl -X POST https://api.guayaba.run/api/v1/agents \ -H "Authorization: Bearer g_master_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support Bot", "llm_provider_name": "openrouter", "llm_provider_model": "openai/gpt-4.1", "bio": ["You are a helpful support agent."], "framework_id": "FRAMEWORK_UUID" }' ``` **Response** (`201`): ``` { "success": true, "message": "Agent created successfully", "data": { "id": "...", "name": "Support Bot", "status": "created" } } ``` *** ### Update Agent Updates an existing agent. Uses PATCH semantics — only provided fields are changed. ``` PUT /agents/{id} ``` **Auth**: Master key only. **Cost**: 10 credits. **Secrets use PATCH semantics**: send `null` or `""` to delete a secret; omit the key entirely to keep it. ``` curl -X PUT https://api.guayaba.run/api/v1/agents/550e8400-... \ -H "Authorization: Bearer g_master_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Bot", "settings": { "model": "anthropic/claude-sonnet-4.6" } }' ``` *** ### Delete Agent Deletes an agent. Stops it first if running. Cascades to API keys and sessions. ``` DELETE /agents/{id} ``` **Auth**: Master key only. **Cost**: Free. ``` curl -X DELETE https://api.guayaba.run/api/v1/agents/550e8400-... \ -H "Authorization: Bearer g_master_YOUR_KEY" ``` *** ### Runtime Control All runtime endpoints require `agent:manage` scope (master keys always pass). #### Get Status ``` GET /agents/{id}/status ``` Returns current status, uptime, and timestamps. **Free.** ``` curl https://api.guayaba.run/api/v1/agents/550e8400-.../status \ -H "Authorization: Bearer g_agent_YOUR_KEY" ``` **Response** (`200`): ``` { "status": "running", "last_boot_execution": "2026-04-09T08:00:00Z", "last_stop_execution": null, "uptime_total_seconds": 86400, "current_uptime": 3600, "server_timestamp": 1744185600000 } ``` #### Health Check ``` GET /agents/{id}/health ``` Returns detailed health for a running agent. **Free.** #### Start Agent ``` POST /agents/{id}/start ``` Boots the agent or resumes from paused. **Cost**: 5 credits. #### Stop Agent ``` POST /agents/{id}/stop ``` Stops the agent and accumulates uptime. **Free.** #### Pause Agent ``` POST /agents/{id}/pause ``` Pauses without stopping the container. **Free.** #### Reload Config ``` POST /agents/{id}/reload ``` Hot-reloads configuration without restarting. Agent must be running. **Cost**: 1 credit. *** ### Agent Status Values | Status | Description | | --------- | ---------------------------------------- | | `created` | Agent created but never started | | `active` | Provisioning / booting | | `running` | Running and accepting requests | | `paused` | Paused (container alive, not processing) | | `stopped` | Stopped (no container) | | `failed` | Failed to start or crashed | *** ### Sessions Manage conversation sessions. All session endpoints require `agent:manage` scope. #### List Sessions ``` GET /agents/{id}/sessions ``` #### Get Session History ``` POST /agents/{id}/sessions/history ``` ``` { "sessionKey": "api:550e8400-...", "limit": 100 } ``` #### Rename Session ``` POST /agents/{id}/sessions/rename ``` ``` { "key": "api:550e8400-...", "label": "Support Conversation #1" } ``` #### Archive Session ``` POST /agents/{id}/sessions/archive ``` ``` { "key": "api:550e8400-..." } ``` #### Delete Session ``` POST /agents/{id}/sessions/delete ``` ``` { "key": "api:550e8400-..." } ``` *** ### Archives #### List Archives ``` GET /agents/{id}/archives ``` #### Restore Archive ``` POST /agents/{id}/archives/restore ``` ``` { "filename": "archive-file.json", "label": "Restored Session" } ``` #### Delete Archive ``` POST /agents/{id}/archives/delete ``` ``` { "filename": "archive-file.json" } ``` *** ### Channels (Telegram) Manage Telegram pairing. All endpoints require `channels` scope. #### List Pairing Requests ``` GET /agents/{id}/channels/telegram/pairing ``` #### List Approved Pairings ``` GET /agents/{id}/channels/telegram/pairing/approved ``` #### Approve Pairing ``` POST /agents/{id}/channels/telegram/pairing/approve ``` ``` { "code": "PAIRING_CODE" } ``` #### Revoke Pairing ``` POST /agents/{id}/channels/telegram/pairing/revoke ``` ``` { "userId": "TELEGRAM_USER_ID" } ``` #### Reject Pairing ``` POST /agents/{id}/channels/telegram/pairing/reject ``` ``` { "code": "PAIRING_CODE" } ``` *** ### Files Upload files to an agent's knowledge base. Requires `files` scope. The agent must be running. ``` POST /agents/{id}/files ``` ``` { "filename": "faq.txt", "content": "Base64 or plain text content...", "mimeType": "text/plain" } ``` *** ### Catalogs Read-only reference data. Any API key type. Responses are cached for 10 minutes. | Endpoint | Description | | --------------------------------------- | -------------------------- | | `GET /catalogs/frameworks` | Available agent frameworks | | `GET /catalogs/frameworks/{id}/clients` | Clients for a framework | | `GET /catalogs/regions` | Deployment regions | | `GET /catalogs/hardware` | Hardware configurations | | `GET /catalogs/models` | Available AI models | # Chat Send messages to your agents programmatically. Supports synchronous JSON responses and real-time SSE streaming. ``` POST /agents/{id}/chat ``` **Auth**: Master key or agent key with `chat` scope. **Cost**: 1 credit per message (base) + LLM cost from the runtime. ### Request ``` { "message": "What's the weather in Madrid?", "sessionKey": "api:550e8400-e29b-41d4-a716-446655440000", "stream": false } ``` | Field | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------------------------------- | | `message` | string | Yes | The user message (max 32,000 chars) | | `sessionKey` | string | No | Reuse an existing session. Must start with `api:`. Auto-generated if omitted. | | `stream` | boolean | No | `true` for SSE streaming, `false` (default) for sync JSON | ### Sync Response When `stream` is `false` (default), the API waits for the full agent response and returns it as JSON. ``` curl -X POST https://api.guayaba.run/api/v1/agents/550e8400-.../chat \ -H "Authorization: Bearer g_master_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Hello, what can you do?"}' ``` **Response** (`200`): ``` { "success": true, "data": { "sessionKey": "api:550e8400-e29b-41d4-a716-446655440000", "message": { "role": "assistant", "content": "I can help you with a variety of tasks..." } } } ``` ### Streaming Response (SSE) When `stream` is `true`, the response is a `text/event-stream` with incremental events. ``` curl -X POST https://api.guayaba.run/api/v1/agents/550e8400-.../chat \ -H "Authorization: Bearer g_master_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Explain quantum computing", "stream": true}' ``` **Event stream**: ``` data: {"type":"session","sessionKey":"api:550e8400-..."} data: {"type":"delta","text":"Quantum"} data: {"type":"delta","text":"Quantum computing is"} data: {"type":"tool","name":"search","phase":"start"} data: {"type":"tool","name":"search","phase":"result","result":"..."} data: {"type":"delta","text":"Quantum computing is a type of computation..."} data: {"type":"done","sessionKey":"api:550e8400-..."} ``` #### Event Types | Type | Description | | --------- | ------------------------------------------------------------------------------------------------ | | `session` | First event. Contains the `sessionKey` for this conversation. | | `delta` | Incremental text from the assistant. The `text` field contains the accumulated content so far. | | `tool` | Tool call lifecycle. `phase: "start"` when a tool is invoked, `phase: "result"` with the output. | | `done` | Final event. The stream is complete. | ### Sessions Each chat message belongs to a **session**. Sessions allow multi-turn conversations where the agent remembers previous context. * If you omit `sessionKey`, a new session is created automatically with an `api:` prefix. * To continue a conversation, pass the `sessionKey` returned in the first response. * Sessions created via the API are prefixed with `api:` to distinguish them from UI sessions. ``` # First message — new session created curl -X POST .../chat -d '{"message": "What is Rust?"}' # Response: sessionKey = "api:abc123..." # Follow-up — same session curl -X POST .../chat -d '{"message": "How does its borrow checker work?", "sessionKey": "api:abc123..."}' ``` You can manage sessions (list, rename, archive, delete) through the [Sessions endpoints](https://github.com/guayabadotrun/gene-seed/blob/main/public/api/agents.md#sessions). ### Tool Calls Agents can use tools (web search, code execution, etc.) during a conversation. In streaming mode, tool calls appear as `tool` events with `phase: "start"` and `phase: "result"`. In sync mode, the final response includes the result after all tools have completed. Tool calls are auto-approved — no user confirmation is needed when using the API. ### Errors | Code | Meaning | | ----- | ---------------------------------------------------- | | `401` | Invalid or missing API key | | `402` | Insufficient credits | | `403` | Key lacks `chat` scope or cannot access this agent | | `404` | Agent not found | | `409` | Agent is not running | | `422` | Validation error (missing `message`, too long, etc.) | | `502` | Agent container unreachable | # Billing & Credits API operations that consume resources are billed in **credits**. Credits are checked before executing the operation — if you don't have enough, the request is rejected with `402`. ### Credit Costs | Operation | Credits | Endpoint | | --------------------------- | ------------ | -------------------------- | | Create agent | 10 | `POST /agents` | | Update agent | 10 | `PUT /agents/{id}` | | Start agent | 5 | `POST /agents/{id}/start` | | Reload config | 1 | `POST /agents/{id}/reload` | | Chat message | 1 + LLM cost | `POST /agents/{id}/chat` | | Stop / Pause / Delete agent | 0 | — | | All read operations (GET) | 0 | — | | Key management | 0 | — | > Credit costs are provisional and subject to change. **Chat billing note**: The base credit (1) is charged on successful completion. The LLM cost (model-dependent token usage) is charged separately by the runtime, same as when using the web UI. ### Checking Your Balance ``` GET /billing/credits ``` **Auth**: Master key only. ``` curl https://api.guayaba.run/api/v1/billing/credits \ -H "Authorization: Bearer g_master_YOUR_KEY" ``` **Response**: ``` { "success": true, "data": { "total_credits": 450, "subscription_credits": 400, "purchased_credits": 50 } } ``` ### Subscription Info ``` GET /billing ``` Returns your current subscription details (tier, status, period dates, trial info). **Auth**: Master key only. ### Available Tiers ``` GET /billing/tiers ``` Returns all subscription tiers with pricing, credit allowances, and feature lists. **Auth**: Master key only. ### Insufficient Credits When you don't have enough credits for an operation, the API returns: ``` 402 Payment Required { "error": "Payment Required", "message": "Insufficient credits for this operation", "required_credits": 10, "available_credits": 3 } ``` The operation is **not** executed. No credits are deducted. ### Subscription Requirement All API endpoints require an active subscription (`active` or `trialing` status). If your subscription is canceled, past due, or absent: ``` 403 Forbidden { "error": "Forbidden", "message": "An active subscription is required to use the API" } ``` # Errors All error responses follow a consistent format: ``` { "error": "ErrorCategory", "message": "Human-readable explanation" } ``` ### Status Codes | Code | Error | Description | | ----- | ------------------- | ------------------------------------------------------------------------------------- | | `401` | Unauthorized | Missing, invalid, revoked, or expired API key | | `402` | Payment Required | Insufficient credits for the operation | | `403` | Forbidden | No active subscription, key lacks required scope, wrong agent, or master key required | | `404` | Not Found | Agent or resource does not exist | | `409` | Conflict | Agent is not in the required state (e.g., chatting with a stopped agent) | | `422` | Validation Error | Request body failed validation | | `429` | Too Many Requests | Rate limit exceeded | | `502` | Bad Gateway | Agent container returned an error or is unreachable | | `503` | Service Unavailable | Agent container is not running | ### Error Examples #### 401 — Invalid API Key ``` { "error": "Unauthorized", "message": "Invalid or revoked API key" } ``` #### 402 — Insufficient Credits ``` { "error": "Payment Required", "message": "Insufficient credits for this operation", "required_credits": 10, "available_credits": 3 } ``` #### 403 — Missing Scope ``` { "error": "Forbidden", "message": "This API key lacks the required scope: agent:manage" } ``` #### 403 — Master Key Required ``` { "error": "Forbidden", "message": "This endpoint requires a master API key" } ``` #### 403 — No Active Master Key (Agent Key Creation) ``` { "error": "Forbidden", "message": "You must have an active master API key before creating agent keys" } ``` #### 403 — No Active Subscription ``` { "error": "Forbidden", "message": "An active subscription is required to use the API" } ``` #### 404 — Agent Not Found ``` { "error": "Not Found", "message": "Agent not found" } ``` #### 422 — Validation Error ``` { "message": "The given data was invalid.", "errors": { "message": ["The message field is required."], "sessionKey": ["The session key must start with 'api:'."] } } ``` #### 502 — Gateway Error ``` { "error": "Bad Gateway", "message": "Failed to communicate with the agent container" } ``` ### Troubleshooting | Symptom | Likely cause | Fix | | ------------------------------------ | -------------------------------------------- | ---------------------------------------------------- | | `401` on every request | Key was revoked or regenerated | Create a new key from the dashboard | | `403` "active subscription required" | Subscription expired or canceled | Reactivate your subscription | | `403` "lacks the required scope" | Agent key missing the needed scope | Create a new agent key with the correct scopes | | `403` "master API key required" | Using an agent key on a master-only endpoint | Use your master key for CRUD and billing operations | | `402` on create/start | Low credit balance | Check balance with `GET /billing/credits` and top up | | `409` on chat/reload | Agent is not running | Start the agent first with `POST /agents/{id}/start` | | `502` on chat | Agent container crashed or is unresponsive | Check agent health with `GET /agents/{id}/health` | # Authentication All endpoints require an API key sent as a **Bearer token**: ``` Authorization: Bearer g_master_ ``` Keys are created from the Guayaba dashboard (Settings → API Keys). #### Key Format | Type | Prefix | Length | | ---------- | ----------- | --------------------------------- | | Master Key | `g_master_` | 57 chars (9-char prefix + 48 hex) | | Agent Key | `g_agent_` | 56 chars (8-char prefix + 48 hex) | Keys are shown **only once** at creation time. The server stores a SHA-256 hash — lost keys cannot be recovered, only regenerated. #### Subscription Requirement All endpoints require the key owner to have an **active subscription** (status: `active` or `trialing`). If the subscription is canceled, past due, or absent, every request returns `403`: ```json { "error": "Forbidden", "message": "An active subscription is required to use the API" } ``` This check runs **after** key validation and **before** any route-specific authorization. # Key Types & Scopes #### Master Key (`g_master_`) * One per user. Creating a new one revokes the previous (and cascade-revokes all agent keys). * Full access to all endpoints and all agents owned by the user. #### Agent Key (`g_agent_`) * One per agent. Tied to a single agent by `agent_id`. * Cannot access other agents (returns `403`). * Access controlled by **scopes** assigned at creation time. #### Scopes | Scope | Description | Default | | -------------- | -------------------------------------------------------- | --------------- | | `agent:read` | View agent details and status | Always included | | `agent:manage` | Start, stop, pause, reload. Manage sessions and archives | No | | `channels` | Manage Telegram pairing (list, approve, revoke, reject) | No | | `files` | Upload files to the agent | No | | `chat` | Send messages to the agent via API | No | A master key implicitly has all scopes. # Billing & Credits Certain write operations consume credits. Credits are charged only on success (HTTP 2xx). | Operation | Credits | Endpoint | | --------------------------- | ------- | -------------------------- | | Create agent | 10 | `POST /agents` | | Update agent | 10 | `PUT /agents/{id}` | | Start agent | 5 | `POST /agents/{id}/start` | | Reload config | 1 | `POST /agents/{id}/reload` | | Chat message | 1 + LLM | `POST /agents/{id}/chat` | | Stop / Pause / Delete agent | 0 | — | | All read operations | 0 | — | Insufficient credits returns `402` **before** executing the operation. > Credit costs are provisional and subject to change. # Caching Catalog endpoints return `Cache-Control: public, max-age=600, s-maxage=600` (10-minute TTL). All other endpoints return fresh data. # Error Responses Errors follow this structure: ```json { "error": "ErrorCategory", "message": "Human-readable explanation" } ``` | Code | Meaning | | ----- | ---------------------------------------------------------------------------- | | `401` | Missing, invalid, or revoked API key | | `402` | Insufficient credits | | `403` | No active subscription / key lacks scope / wrong agent / master key required | | `404` | Agent or resource not found | | `422` | Validation errors | | `502` | Proxy request to agent container failed | | `503` | Agent container not running | # Agent Status Values | Status | Description | | --------- | ------------------------------------------------- | | `created` | Agent created but never started | | `active` | Agent is provisioning / booting | | `running` | Agent is running and accepting requests | | `paused` | Agent is paused (container alive, not processing) | | `stopped` | Agent is stopped (no container) | | `failed` | Agent failed to start or crashed | # Agents CRUD operations on AI agents ## List user's agents > Returns a paginated list of all agents belonging to the API key owner.\ > Works with any API key type (master or agent).
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/agents":{"get":{"tags":["Agents"],"summary":"List user's agents","description":"Returns a paginated list of all agents belonging to the API key owner.\nWorks with any API key type (master or agent).\n","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","default":100}},{"name":"page","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Paginated list of agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}} ``` ## Create a new agent > Creates a new AI agent. Requires a \*\*master key\*\*.\ > Charges \*\*10 credits\*\*.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"AgentSettingsInput":{"type":"object","description":"Input schema for creating or updating an agent","properties":{"name":{"type":"string","maxLength":255},"llm_provider_name":{"type":"string"},"llm_provider_model":{"type":"string"},"bio":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":2000}},"knowledge":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":5000}},"channels":{"type":"array","maxItems":10,"items":{"type":"string"}},"model_provider":{"type":"string"},"settings":{"type":"object","properties":{"model":{"type":"string","maxLength":255},"thinking":{"type":"string","enum":["off","low","medium","high"]},"extra_instructions":{"type":"string","maxLength":10000},"secrets":{"type":"object","description":"Key-value map. Send null or \"\" to delete a secret; omit the key to keep it.","additionalProperties":{"type":"string","nullable":true}},"trusted_proxies":{"type":"array","maxItems":10,"items":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer","minimum":1,"maximum":10080},"POST_INTERVAL_MAX":{"type":"integer","minimum":1,"maximum":10080},"TWITTER_POLL_INTERVAL":{"type":"integer","minimum":10,"maximum":86400},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer","minimum":1,"maximum":100},"ACTION_INTERVAL":{"type":"integer","minimum":1,"maximum":10080}}},"auto_generation_prompt":{"type":"string","maxLength":10000},"auto_enhancement_prompt":{"type":"string","maxLength":10000},"framework_id":{"type":"string","format":"uuid"},"region_id":{"type":"string","format":"uuid"},"ram_id":{"type":"string","format":"uuid"},"disk_id":{"type":"string","format":"uuid"},"gpu_id":{"type":"string","format":"uuid"},"cpu_id":{"type":"string","format":"uuid"}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents":{"post":{"tags":["Agents"],"summary":"Create a new agent","description":"Creates a new AI agent. Requires a **master key**.\nCharges **10 credits**.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSettingsInput"}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/MasterKeyRequired"},"422":{"description":"Validation error"}}}}}} ``` ## Show agent details > Returns full details for a specific agent.\ > \- \*\*Master key\*\*: can access any of the user's agents.\ > \- \*\*Agent key\*\*: requires \`agent:read\` scope (always included). Can only access its linked agent.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}":{"get":{"tags":["Agents"],"summary":"Show agent details","description":"Returns full details for a specific agent.\n- **Master key**: can access any of the user's agents.\n- **Agent key**: requires `agent:read` scope (always included). Can only access its linked agent.\n","responses":{"200":{"description":"Agent details","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Agent key does not have access to this agent"},"404":{"description":"Agent not found"}}}}}} ``` ## Update an agent > Updates an existing agent (PATCH semantics — only provided fields are changed).\ > Requires a \*\*master key\*\*. Charges \*\*10 credits\*\*.\ > \ > \*\*Secrets use PATCH semantics\*\*: sending \`null\` or \`""\` for a secret key deletes it;\ > omitting the \`secrets\` key entirely preserves all existing secrets.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"AgentSettingsInput":{"type":"object","description":"Input schema for creating or updating an agent","properties":{"name":{"type":"string","maxLength":255},"llm_provider_name":{"type":"string"},"llm_provider_model":{"type":"string"},"bio":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":2000}},"knowledge":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":5000}},"channels":{"type":"array","maxItems":10,"items":{"type":"string"}},"model_provider":{"type":"string"},"settings":{"type":"object","properties":{"model":{"type":"string","maxLength":255},"thinking":{"type":"string","enum":["off","low","medium","high"]},"extra_instructions":{"type":"string","maxLength":10000},"secrets":{"type":"object","description":"Key-value map. Send null or \"\" to delete a secret; omit the key to keep it.","additionalProperties":{"type":"string","nullable":true}},"trusted_proxies":{"type":"array","maxItems":10,"items":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer","minimum":1,"maximum":10080},"POST_INTERVAL_MAX":{"type":"integer","minimum":1,"maximum":10080},"TWITTER_POLL_INTERVAL":{"type":"integer","minimum":10,"maximum":86400},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer","minimum":1,"maximum":100},"ACTION_INTERVAL":{"type":"integer","minimum":1,"maximum":10080}}},"auto_generation_prompt":{"type":"string","maxLength":10000},"auto_enhancement_prompt":{"type":"string","maxLength":10000},"framework_id":{"type":"string","format":"uuid"},"region_id":{"type":"string","format":"uuid"},"ram_id":{"type":"string","format":"uuid"},"disk_id":{"type":"string","format":"uuid"},"gpu_id":{"type":"string","format":"uuid"},"cpu_id":{"type":"string","format":"uuid"}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}":{"put":{"tags":["Agents"],"summary":"Update an agent","description":"Updates an existing agent (PATCH semantics — only provided fields are changed).\nRequires a **master key**. Charges **10 credits**.\n\n**Secrets use PATCH semantics**: sending `null` or `\"\"` for a secret key deletes it;\nomitting the `secrets` key entirely preserves all existing secrets.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSettingsInput"}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Agent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/MasterKeyRequired"},"404":{"description":"Agent not found"}}}}}} ``` ## Delete an agent > Deletes an agent. Stops it first if running/paused.\ > Cascades to related API keys and runtime sessions.\ > Requires a \*\*master key\*\*. No credit charge.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Agents","description":"CRUD operations on AI agents"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}":{"delete":{"tags":["Agents"],"summary":"Delete an agent","description":"Deletes an agent. Stops it first if running/paused.\nCascades to related API keys and runtime sessions.\nRequires a **master key**. No credit charge.\n","responses":{"200":{"description":"Agent deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"},"404":{"description":"Agent not found"}}}}}} ``` # Runtime Agent lifecycle control (start, stop, pause, reload, health) ## Get agent runtime status > Returns current status, uptime, and last boot/stop timestamps.\ > Requires \`agent:manage\` scope (master keys always pass).
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/status":{"get":{"tags":["Runtime"],"summary":"Get agent runtime status","description":"Returns current status, uptime, and last boot/stop timestamps.\nRequires `agent:manage` scope (master keys always pass).\n","responses":{"200":{"description":"Agent status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["created","active","running","paused","stopped","failed","removed"]},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"current_uptime":{"type":"integer","description":"Seconds since last boot (0 if not running)"},"server_timestamp":{"type":"integer","description":"Server time in epoch milliseconds"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Start an agent > Boots the agent (or resumes from paused).\ > Requires \`agent:manage\` scope. Charges \*\*5 credits\*\*.\ > Subject to subscription guards (max running agents, allowed channels).
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/start":{"post":{"tags":["Runtime"],"summary":"Start an agent","description":"Boots the agent (or resumes from paused).\nRequires `agent:manage` scope. Charges **5 credits**.\nSubject to subscription guards (max running agents, allowed channels).\n","responses":{"200":{"description":"Agent started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"},"previous_status":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Stop an agent > Stops the agent and accumulates uptime. Requires \`agent:manage\` scope. No credit charge.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/stop":{"post":{"tags":["Runtime"],"summary":"Stop an agent","description":"Stops the agent and accumulates uptime. Requires `agent:manage` scope. No credit charge.\n","responses":{"200":{"description":"Agent stopped"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Pause an agent > Pauses the agent without stopping the container. Requires \`agent:manage\` scope. No credit charge.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/pause":{"post":{"tags":["Runtime"],"summary":"Pause an agent","description":"Pauses the agent without stopping the container. Requires `agent:manage` scope. No credit charge.\n","responses":{"200":{"description":"Agent paused"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Reload agent config > Hot-reloads the agent configuration without restarting.\ > Agent must be in \`running\` state. Requires \`agent:manage\` scope.\ > Charges \*\*1 credit\*\*.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/reload":{"post":{"tags":["Runtime"],"summary":"Reload agent config","description":"Hot-reloads the agent configuration without restarting.\nAgent must be in `running` state. Requires `agent:manage` scope.\nCharges **1 credit**.\n","responses":{"200":{"description":"Config reloaded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}}}},"400":{"description":"Agent is not running"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Agent health check > Returns health status for a running agent. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/health":{"get":{"tags":["Runtime"],"summary":"Agent health check","description":"Returns health status for a running agent. Requires `agent:manage` scope.\n","responses":{"200":{"description":"Agent is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"agent_status":{"type":"string"},"health":{"type":"object","properties":{"status":{"type":"string"},"launcher":{"type":"string"},"gateway":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"},"503":{"description":"Agent container not running"}}}}}} ``` # Catalogs Read-only reference data (frameworks, regions, hardware, models). Cached 10 min. ## List available frameworks > Returns all available agent frameworks. Any API key type. Cached 10 min.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Catalogs","description":"Read-only reference data (frameworks, regions, hardware, models). Cached 10 min."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/catalogs/frameworks":{"get":{"tags":["Catalogs"],"summary":"List available frameworks","description":"Returns all available agent frameworks. Any API key type. Cached 10 min.\n","responses":{"200":{"description":"List of frameworks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFramework"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}} ``` ## List framework clients > Returns available clients for a specific framework. Any API key type. Cached 10 min.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Catalogs","description":"Read-only reference data (frameworks, regions, hardware, models). Cached 10 min."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/catalogs/frameworks/{frameworkId}/clients":{"get":{"tags":["Catalogs"],"summary":"List framework clients","description":"Returns available clients for a specific framework. Any API key type. Cached 10 min.\n","responses":{"200":{"description":"List of framework clients"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}} ``` ## List available regions > Returns all available deployment regions. Any API key type. Cached 10 min.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Catalogs","description":"Read-only reference data (frameworks, regions, hardware, models). Cached 10 min."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/catalogs/regions":{"get":{"tags":["Catalogs"],"summary":"List available regions","description":"Returns all available deployment regions. Any API key type. Cached 10 min.\n","responses":{"200":{"description":"List of regions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRegion"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}} ``` ## List available hardware configs > Returns all available hardware configurations. Any API key type. Cached 10 min.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Catalogs","description":"Read-only reference data (frameworks, regions, hardware, models). Cached 10 min."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/catalogs/hardware":{"get":{"tags":["Catalogs"],"summary":"List available hardware configs","description":"Returns all available hardware configurations. Any API key type. Cached 10 min.\n","responses":{"200":{"description":"List of hardware configs"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}} ``` ## List available models > Returns all available AI models. Any API key type. Cached 10 min.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Catalogs","description":"Read-only reference data (frameworks, regions, hardware, models). Cached 10 min."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"CatalogModel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"model_id":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_free":{"type":"boolean"},"is_default":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"Forbidden — Active subscription required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/catalogs/models":{"get":{"tags":["Catalogs"],"summary":"List available models","description":"Returns all available AI models. Any API key type. Cached 10 min.\n","responses":{"200":{"description":"List of models","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogModel"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/SubscriptionRequired"}}}}}} ``` # Channels Telegram pairing management. Requires `channels` scope. ## List Telegram pairing requests > Returns pending Telegram pairing requests for an agent. Requires \`channels\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Channels","description":"Telegram pairing management. Requires `channels` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/channels/telegram/pairing":{"get":{"tags":["Channels"],"summary":"List Telegram pairing requests","description":"Returns pending Telegram pairing requests for an agent. Requires `channels` scope.\n","responses":{"200":{"description":"List of pairing requests"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## List approved Telegram pairings > Returns approved Telegram pairings for an agent. Requires \`channels\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Channels","description":"Telegram pairing management. Requires `channels` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/channels/telegram/pairing/approved":{"get":{"tags":["Channels"],"summary":"List approved Telegram pairings","description":"Returns approved Telegram pairings for an agent. Requires `channels` scope.\n","responses":{"200":{"description":"List of approved pairings"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Approve a Telegram pairing > Approves a pending Telegram pairing request. Requires \`channels\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Channels","description":"Telegram pairing management. Requires `channels` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/channels/telegram/pairing/approve":{"post":{"tags":["Channels"],"summary":"Approve a Telegram pairing","description":"Approves a pending Telegram pairing request. Requires `channels` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The pairing code shown to the Telegram user"}}}}}},"responses":{"200":{"description":"Pairing approved"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Revoke a Telegram pairing > Revokes an approved Telegram pairing. Requires \`channels\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Channels","description":"Telegram pairing management. Requires `channels` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/channels/telegram/pairing/revoke":{"post":{"tags":["Channels"],"summary":"Revoke a Telegram pairing","description":"Revokes an approved Telegram pairing. Requires `channels` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["userId"],"properties":{"userId":{"type":"string","description":"Telegram user ID to revoke"}}}}}},"responses":{"200":{"description":"Pairing revoked"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Reject a Telegram pairing > Rejects a pending Telegram pairing request. Requires \`channels\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Channels","description":"Telegram pairing management. Requires `channels` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/channels/telegram/pairing/reject":{"post":{"tags":["Channels"],"summary":"Reject a Telegram pairing","description":"Rejects a pending Telegram pairing request. Requires `channels` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The pairing code to reject"}}}}}},"responses":{"200":{"description":"Pairing rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` # Files Upload files to an agent. Requires `files` scope. ## Upload a file to an agent > Uploads a file to the agent's knowledge base. Requires \`files\` scope.\ > The agent must be running.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Files","description":"Upload files to an agent. Requires `files` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/files":{"post":{"tags":["Files"],"summary":"Upload a file to an agent","description":"Uploads a file to the agent's knowledge base. Requires `files` scope.\nThe agent must be running.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","content","mimeType"],"properties":{"filename":{"type":"string","maxLength":255},"content":{"type":"string"},"mimeType":{"type":"string","maxLength":100}}}}}},"responses":{"200":{"description":"File uploaded"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` # Chat Send messages to an agent. Supports sync and SSE streaming. Requires `chat` scope. ## Send a message to an agent > Sends a chat message to the agent. By default returns a sync JSON response with\ > the full assistant reply. Set \`stream: true\` to receive Server-Sent Events (SSE)\ > with incremental deltas.\ > \ > \*\*Sessions\*\*: If no \`sessionKey\` is provided, a new session is created with an\ > \`api:\` prefix. Reuse the returned \`sessionKey\` to continue a conversation.\ > \ > \*\*Billing\*\*: Each message costs 1 credit (base) plus the LLM cost charged by the runtime.\ > \ > Requires \`chat\` scope on agent keys. Master keys have implicit access.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Chat","description":"Send messages to an agent. Supports sync and SSE streaming. Requires `chat` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/agents/{id}/chat":{"post":{"tags":["Chat"],"summary":"Send a message to an agent","description":"Sends a chat message to the agent. By default returns a sync JSON response with\nthe full assistant reply. Set `stream: true` to receive Server-Sent Events (SSE)\nwith incremental deltas.\n\n**Sessions**: If no `sessionKey` is provided, a new session is created with an\n`api:` prefix. Reuse the returned `sessionKey` to continue a conversation.\n\n**Billing**: Each message costs 1 credit (base) plus the LLM cost charged by the runtime.\n\nRequires `chat` scope on agent keys. Master keys have implicit access.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":32000,"description":"The user message to send to the agent."},"sessionKey":{"type":"string","maxLength":255,"pattern":"^api:[a-zA-Z0-9\\-]+$","description":"Reuse an existing session. Must start with `api:`. If omitted, a new\nsession key is generated automatically.\n"},"stream":{"type":"boolean","default":false,"description":"If `true`, the response is an SSE stream (`text/event-stream`).\nIf `false` (default), waits for the full response and returns JSON.\n"}}}}}},"responses":{"200":{"description":"Sync response with the full assistant message","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionKey":{"type":"string"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}}}}}}},"text/event-stream":{"schema":{"type":"string","description":"SSE stream (when `stream: true`). Events:\n- `{\"type\":\"session\",\"sessionKey\":\"api:...\"}` — first event\n- Gateway events forwarded as-is (deltas, tool calls, etc.)\n- `{\"type\":\"done\",\"sessionKey\":\"api:...\"}` — terminal event\n"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/ScopeForbidden"},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Agent is not running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"502":{"description":"Gateway error — agent is unreachable or returned an error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` # Sessions Manage conversation sessions and archives. Requires `agent:manage` scope. ## List agent sessions > Returns active chat sessions for an agent. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Session":{"type":"object","properties":{"key":{"type":"string"},"sessionId":{"type":"string","format":"uuid"},"sessionFile":{"type":"string"},"label":{"type":"string","nullable":true},"updatedAt":{"type":"integer","description":"Unix timestamp in milliseconds"},"chatType":{"type":"string"},"lastChannel":{"type":"string"},"origin":{"type":"object"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/sessions":{"get":{"tags":["Sessions"],"summary":"List agent sessions","description":"Returns active chat sessions for an agent. Requires `agent:manage` scope.\n","responses":{"200":{"description":"List of sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Get session history > Returns message history for a specific session. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"ChatMessage":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"description":"String or array of content blocks","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}]},"timestamp":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/sessions/history":{"post":{"tags":["Sessions"],"summary":"Get session history","description":"Returns message history for a specific session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionKey"],"properties":{"sessionKey":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":1000}}}}}},"responses":{"200":{"description":"Session message history","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Rename a session > Renames a chat session. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/sessions/rename":{"post":{"tags":["Sessions"],"summary":"Rename a session","description":"Renames a chat session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"label":{"type":"string","maxLength":255,"nullable":true}}}}}},"responses":{"200":{"description":"Session renamed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Archive a session > Archives a chat session. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/sessions/archive":{"post":{"tags":["Sessions"],"summary":"Archive a session","description":"Archives a chat session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}}}},"responses":{"200":{"description":"Session archived"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Delete a session > Permanently deletes a chat session. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/sessions/delete":{"post":{"tags":["Sessions"],"summary":"Delete a session","description":"Permanently deletes a chat session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}}}},"responses":{"200":{"description":"Session deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## List archived sessions > Returns archived chat sessions for an agent. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Archive":{"type":"object","properties":{"filename":{"type":"string"},"label":{"type":"string","nullable":true},"archivedAt":{"type":"string"},"sessionId":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/archives":{"get":{"tags":["Sessions"],"summary":"List archived sessions","description":"Returns archived chat sessions for an agent. Requires `agent:manage` scope.\n","responses":{"200":{"description":"List of archived sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Archive"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Restore an archived session > Restores an archived session back to active. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/archives/restore":{"post":{"tags":["Sessions"],"summary":"Restore an archived session","description":"Restores an archived session back to active. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string"},"label":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"Session restored"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` ## Delete an archived session > Permanently deletes an archived session. Requires \`agent:manage\` scope.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Sessions","description":"Manage conversation sessions and archives. Requires `agent:manage` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/archives/delete":{"post":{"tags":["Sessions"],"summary":"Delete an archived session","description":"Permanently deletes an archived session. Requires `agent:manage` scope.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string"}}}}}},"responses":{"200":{"description":"Archive deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}} ``` # Billing Subscription, tiers, and credits. Requires master key. ## Show billing info > Returns current subscription and billing details. Requires a \*\*master key\*\*.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Billing","description":"Subscription, tiers, and credits. Requires master key."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"tier_slug":{"type":"string"},"status":{"type":"string","enum":["active","trialing","past_due","canceled","incomplete","incomplete_expired","unpaid","paused"]},"stripe_subscription_id":{"type":"string","nullable":true},"stripe_customer_id":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"monthly_credits":{"type":"integer"},"current_period_start":{"type":"string","format":"date-time","nullable":true},"current_period_end":{"type":"string","format":"date-time","nullable":true},"trial_start":{"type":"string","format":"date-time","nullable":true},"trial_end":{"type":"string","format":"date-time","nullable":true},"cancel_at_period_end":{"type":"boolean","nullable":true},"cancel_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tier":{"$ref":"#/components/schemas/Tier"}}},"Tier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"monthly_credits":{"type":"integer"},"price":{"type":"number","format":"float"},"features":{"type":"array","nullable":true,"items":{"type":"string"}},"max_running_agents":{"type":"integer","nullable":true},"allowed_channels":{"type":"array","nullable":true,"items":{"type":"string"}},"can_buy_credit_packages":{"type":"boolean"},"trial_days":{"type":"integer"},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/billing":{"get":{"tags":["Billing"],"summary":"Show billing info","description":"Returns current subscription and billing details. Requires a **master key**.\n","responses":{"200":{"description":"Billing details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Subscription"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"}}}}}} ``` ## List subscription tiers > Returns available subscription tiers and pricing. Requires a \*\*master key\*\*.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Billing","description":"Subscription, tiers, and credits. Requires master key."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Tier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"monthly_credits":{"type":"integer"},"price":{"type":"number","format":"float"},"features":{"type":"array","nullable":true,"items":{"type":"string"}},"max_running_agents":{"type":"integer","nullable":true},"allowed_channels":{"type":"array","nullable":true,"items":{"type":"string"}},"can_buy_credit_packages":{"type":"boolean"},"trial_days":{"type":"integer"},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/billing/tiers":{"get":{"tags":["Billing"],"summary":"List subscription tiers","description":"Returns available subscription tiers and pricing. Requires a **master key**.\n","responses":{"200":{"description":"Subscription tiers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Tier"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"}}}}}} ``` ## Get credits breakdown > Returns detailed credits breakdown (subscription vs purchased). Requires a \*\*master key\*\*.
```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Billing","description":"Subscription, tiers, and credits. Requires master key."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"CreditBreakdown":{"type":"object","properties":{"total_credits":{"type":"integer"},"subscription_credits":{"type":"integer"},"purchased_credits":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/billing/credits":{"get":{"tags":["Billing"],"summary":"Get credits breakdown","description":"Returns detailed credits breakdown (subscription vs purchased). Requires a **master key**.\n","responses":{"200":{"description":"Credits breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CreditBreakdown"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"}}}}}} ``` # Models ## The Error object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}} ``` ## The Agent object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}}}}} ``` ## The AgentSettingsInput object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"AgentSettingsInput":{"type":"object","description":"Input schema for creating or updating an agent","properties":{"name":{"type":"string","maxLength":255},"llm_provider_name":{"type":"string"},"llm_provider_model":{"type":"string"},"bio":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":2000}},"knowledge":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":5000}},"channels":{"type":"array","maxItems":10,"items":{"type":"string"}},"model_provider":{"type":"string"},"settings":{"type":"object","properties":{"model":{"type":"string","maxLength":255},"thinking":{"type":"string","enum":["off","low","medium","high"]},"extra_instructions":{"type":"string","maxLength":10000},"secrets":{"type":"object","description":"Key-value map. Send null or \"\" to delete a secret; omit the key to keep it.","additionalProperties":{"type":"string","nullable":true}},"trusted_proxies":{"type":"array","maxItems":10,"items":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer","minimum":1,"maximum":10080},"POST_INTERVAL_MAX":{"type":"integer","minimum":1,"maximum":10080},"TWITTER_POLL_INTERVAL":{"type":"integer","minimum":10,"maximum":86400},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer","minimum":1,"maximum":100},"ACTION_INTERVAL":{"type":"integer","minimum":1,"maximum":10080}}},"auto_generation_prompt":{"type":"string","maxLength":10000},"auto_enhancement_prompt":{"type":"string","maxLength":10000},"framework_id":{"type":"string","format":"uuid"},"region_id":{"type":"string","format":"uuid"},"ram_id":{"type":"string","format":"uuid"},"disk_id":{"type":"string","format":"uuid"},"gpu_id":{"type":"string","format":"uuid"},"cpu_id":{"type":"string","format":"uuid"}}}}}} ``` ## The CatalogFramework object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}}}}} ``` ## The CatalogRegion object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}}}}} ``` ## The CatalogHardwareOption object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}}}}} ``` ## The CatalogChannel object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"CatalogChannel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"always_on":{"type":"boolean"}}}}}} ``` ## The CatalogModel object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"CatalogModel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"model_id":{"type":"string"},"provider":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_free":{"type":"boolean"},"is_default":{"type":"boolean"}}}}}} ``` ## The Session object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"Session":{"type":"object","properties":{"key":{"type":"string"},"sessionId":{"type":"string","format":"uuid"},"sessionFile":{"type":"string"},"label":{"type":"string","nullable":true},"updatedAt":{"type":"integer","description":"Unix timestamp in milliseconds"},"chatType":{"type":"string"},"lastChannel":{"type":"string"},"origin":{"type":"object"}}}}}} ``` ## The ChatMessage object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"ChatMessage":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"description":"String or array of content blocks","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}]},"timestamp":{"type":"integer"}}}}}} ``` ## The Archive object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"Archive":{"type":"object","properties":{"filename":{"type":"string"},"label":{"type":"string","nullable":true},"archivedAt":{"type":"string"},"sessionId":{"type":"string"}}}}}} ``` ## The Subscription object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"Subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"tier_slug":{"type":"string"},"status":{"type":"string","enum":["active","trialing","past_due","canceled","incomplete","incomplete_expired","unpaid","paused"]},"stripe_subscription_id":{"type":"string","nullable":true},"stripe_customer_id":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"monthly_credits":{"type":"integer"},"current_period_start":{"type":"string","format":"date-time","nullable":true},"current_period_end":{"type":"string","format":"date-time","nullable":true},"trial_start":{"type":"string","format":"date-time","nullable":true},"trial_end":{"type":"string","format":"date-time","nullable":true},"cancel_at_period_end":{"type":"boolean","nullable":true},"cancel_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tier":{"$ref":"#/components/schemas/Tier"}}},"Tier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"monthly_credits":{"type":"integer"},"price":{"type":"number","format":"float"},"features":{"type":"array","nullable":true,"items":{"type":"string"}},"max_running_agents":{"type":"integer","nullable":true},"allowed_channels":{"type":"array","nullable":true,"items":{"type":"string"}},"can_buy_credit_packages":{"type":"boolean"},"trial_days":{"type":"integer"},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}} ``` ## The Tier object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"Tier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"monthly_credits":{"type":"integer"},"price":{"type":"number","format":"float"},"features":{"type":"array","nullable":true,"items":{"type":"string"}},"max_running_agents":{"type":"integer","nullable":true},"allowed_channels":{"type":"array","nullable":true,"items":{"type":"string"}},"can_buy_credit_packages":{"type":"boolean"},"trial_days":{"type":"integer"},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}} ``` ## The CreditBreakdown object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"CreditBreakdown":{"type":"object","properties":{"total_credits":{"type":"integer"},"subscription_credits":{"type":"integer"},"purchased_credits":{"type":"integer"}}}}}} ``` ## The ValidationError object ```json {"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"components":{"schemas":{"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}} ```