Your agent,
through an API.

A practical guide to what works today. Start with one published agent, one key, and one request.

Two different connections

Your first API request

1. Create an account and verify your email.
2. Open Agents, create an agent, add instructions, and Publish.
3. As the workspace owner, open the agent’s API access tab and create a key. Copy the key once and note the agent ID shown in the endpoint example.
4. Keep the key on your server or in a private API client. Create UUIDs for the conversation and request.

Set these values locally. The example uses your shell’s uuidgen command; JavaScript can use crypto.randomUUID().

export AGENT_ID="your-agent-id"
export AGENT_API_KEY="your-private-agent-key"
export CONVERSATION_ID="$(uuidgen)"
export REQUEST_ID="$(uuidgen)"

curl "https://app.agnosticagents.com/api/v1/agents/$AGENT_ID/messages" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"conversationId\":\"$CONVERSATION_ID\",\"requestId\":\"$REQUEST_ID\",\"message\":\"Hello. My name is Ada.\"}"

Replace the two private values. Never put an agent API key in browser JavaScript, source control, or a public collection.

A ready-to-import Postman collection

A collection is a saved set of example API requests. This one includes start a conversation, continue it, and replay the last request. It generates UUIDs for you and contains no credentials.

1. Import the JSON file into Postman.
2. In the collection’s variables, enter agentId and your private agentApiKey. Keep the key local and do not share or sync it publicly.
3. Send the first request, then the second. The second reuses the conversation ID with a new request ID.
4. The replay request resends the previous request body exactly. A completed request returns its saved receipt.

Send a message

Base URL: https://app.agnosticagents.com. Requires Authorization: Bearer <agent-key> and Content-Type: application/json.

The endpoint accepts JSON—not multipart file uploads or base64 documents. Extract file text on your server before including it. For persistent document knowledge, upload files in the agent’s Knowledge tab instead. Total request-body limit: 750,000 bytes.

Authentication and scope

A key is scoped to one agent and acts as its owner. Keys expire after 30 days and can be revoked in the app. The caller must retain the required workspace permissions. A conversation belongs to its user; another workspace member cannot automatically read it.

Response format

Successful requests return HTTP 200 with a complete JSON reply. Streaming is not available yet.

{
  "text": "Hello Ada. How can I help?",
  "tools": [],
  "model": "upstage/solar-pro4",
  "conversationId": "11111111-1111-4111-8111-111111111111",
  "requestId": "22222222-2222-4222-8222-222222222222"
}

This is an illustrative response shape, not a model-output guarantee. tools contains { tool, result } entries for tools that ran. When knowledge is retrieved, an optional sources array contains { fileId, name, passage }. The server selects the configured model; do not assume the returned model name will stay fixed.

Conversations and safe retries

• New message: keep the conversation ID, generate a new request ID.
• Network timeout: retry the identical body with the same request ID. Do not immediately generate a new ID: the first request may still complete.
• Request still running: wait before retrying. Only one active turn is allowed in a conversation.
• Completed request: an identical retry returns the stored receipt without another model run.
• Definitively failed request: the API requires a new request ID. An uncertain external tool action should be checked before retrying; do not assume every external write is reversible or exactly-once.

New conversations snapshot the published configuration. Existing conversations retain that version’s instructions; current published grants still constrain knowledge and tools. Start a new conversation to use newly published instructions. Unsaved editor changes are not used by this endpoint.

Limits and errors

Errors use { "error": "Human-readable explanation" }. Inspect the HTTP status and message; there are no stable machine-readable error codes yet.

Current limits include 20 new agent requests per minute per user per agent, and 100 stored conversations per user per agent, including archived conversations. These are beta limits. Keys are limited to 10 active keys per agent.

Connecting an external API tool

This is separate from calling an agent. In Integrations → Custom API tools, define what your own service allows the agent to do.

1. Give the tool a clear name and description.
2. Configure the HTTPS endpoint, request method, fixed values, and the input fields the agent may supply.
3. Add authentication privately. The agent should never receive or generate the credential.
4. Alternatively, import supported operations from an OpenAPI JSON specification, then review each tool.
5. In the agent’s Tools tab, grant the specific tool and publish the changes. Write actions require explicit permission.

A tool does not grant arbitrary network access. Destinations and allowed inputs are configured on the server; credentials stay private. Read actions can still consume external-provider quotas. Check the external service’s permissions and charges.

Usage and credits

Web chat, agent API requests, and metered AI features use the same owner-account allowance across workspaces. Billing shows consumed, reserved, and remaining credits, plus AI and estimated execution consumption. Token and spending safeguards also remain in force.

Requests reserve an estimate before execution and settle measured costs afterward. Uncertain provider charges retain their reservation. A failed execution may still consume compute or provider usage; an identical successful receipt replay does not rerun the agent.

Execution charges currently use a reference estimate, not a reconciled hosting invoice. Paid checkout remains disabled during beta. This guide does not promise unlimited usage, automatic overages, or paid-tool fees included in every plan.