{"openapi":"3.1.0","info":{"title":"Agnose API","version":"0.1.0","summary":"Use the AI agents you rent on Agnose from your own code.","description":"List your agent instances, send them messages, read replies and usage. Authenticate with a personal key from https://agneos.com/app/cuenta/api. The same operations are available as an MCP server at https://agneos.com/api/mcp. Webhook events: run.completed, run.failed, instance.cancelled.","contact":{"name":"Agnose","url":"https://agneos.com/contacto"},"termsOfService":"https://agneos.com/terminos"},"servers":[{"url":"https://agneos.com/api/v1"}],"externalDocs":{"description":"Guide","url":"https://agneos.com/desarrolladores"},"security":[{"bearer":[]}],"tags":[{"name":"instances"},{"name":"runs"},{"name":"usage"}],"paths":{"/instances":{"get":{"operationId":"listInstances","tags":["instances"],"summary":"List your active and paused instances.","x-scope":"instances:read","responses":{"200":{"description":"Your instances.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Instance"}}}}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (rate_limited) or the plan's daily message limit (plan_limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/instances/{id}/messages":{"post":{"operationId":"sendMessage","tags":["runs"],"summary":"Send a message to an instance; returns the run to poll.","x-scope":"messages:write","parameters":[{"name":"id","in":"path","required":true,"description":"Instance id (uuid).","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":8000}}}}}},"responses":{"202":{"description":"Accepted; poll the run.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such instance, or it is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (rate_limited) or the plan's daily message limit (plan_limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/instances/{id}/runs/{runId}":{"get":{"operationId":"getRun","tags":["runs"],"summary":"Get a run: status and, once done, the reply.","x-scope":"runs:read","parameters":[{"name":"id","in":"path","required":true,"description":"Instance id (uuid).","schema":{"type":"string","format":"uuid"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such instance or run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (rate_limited) or the plan's daily message limit (plan_limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/usage":{"get":{"operationId":"getUsage","tags":["usage"],"summary":"Usage per instance over the last days, and today's messages against the plan limit.","x-scope":"usage:read","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (rate_limited) or the plan's daily message limit (plan_limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}}},"webhooks":{"run.completed":{"post":{"summary":"run.completed event, signed with the agnose-signature header (t=<unix>,v1=<hex HMAC-SHA256 of \"t.body\">).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges; otherwise it is retried with backoff up to 8 times."}}}},"run.failed":{"post":{"summary":"run.failed event, signed with the agnose-signature header (t=<unix>,v1=<hex HMAC-SHA256 of \"t.body\">).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges; otherwise it is retried with backoff up to 8 times."}}}},"instance.cancelled":{"post":{"summary":"instance.cancelled event, signed with the agnose-signature header (t=<unix>,v1=<hex HMAC-SHA256 of \"t.body\">).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges; otherwise it is retried with backoff up to 8 times."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"agn_…","description":"Personal API key. Scopes: instances:read, messages:write, runs:read, usage:read."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","invalid","plan_limit","rate_limited","internal"]},"message":{"type":"string"}}}}},"Instance":{"type":"object","required":["id","status","agent","plan","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused"]},"agent":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"url":{"type":"string","format":"uri"}}},"plan":{"type":"object","properties":{"name":{"type":"string"},"messages_per_day":{"type":["integer","null"]}}},"created_at":{"type":"string","format":"date-time"}}},"Run":{"type":"object","required":["id","instance_id","status"],"properties":{"id":{"type":"string"},"instance_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","done","failed"]},"reply":{"type":["string","null"]},"error":{"type":["string","null"]}}},"Usage":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"days":{"type":"integer"},"instances":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent":{"type":"string"},"messages_today":{"type":"integer"},"messages_per_day":{"type":["integer","null"]},"totals":{"type":"object","additionalProperties":{"type":"integer"}}}}}}},"WebhookEvent":{"type":"object","required":["id","type","created","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["run.completed","run.failed","instance.cancelled","ping"]},"created":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}}