{"openapi":"3.1.0","info":{"title":"Toolspin Agent API","version":"1.0.0","description":"Execute noninteractive tools using your own InstaVM account and existing billing. Preparation and failed runs can incur compute usage. Reuse an idempotency key when retrying the same run. Results and idempotency records expire after 24 hours. If billing.cleanup is pending, keep polling; confirmed and not_created require no further cleanup. Pending cleanup can still incur usage. Interactive TUI workflows require the browser terminal."},"servers":[{"url":"/"}],"paths":{"/api/v1/tools":{"get":{"operationId":"listTools","summary":"Search runnable tools","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Catalog page","content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"total":{"type":"integer"},"next_offset":{"type":["integer","null"]}}}}}},"400":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/runs":{"post":{"operationId":"createRun","summary":"Start one billed tool run","security":[{"InstaVMKey":[]},{"InstaVMBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"Existing terminal run returned for an idempotent retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"202":{"description":"Accepted; poll Location or poll_url every two seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/runs/{id}":{"get":{"operationId":"getRun","summary":"Read your result and reconcile pending cleanup","security":[{"InstaVMKey":[]},{"InstaVMBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}],"responses":{"200":{"description":"Current run. Terminal states: completed, failed, interrupted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"400":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account":{"get":{"operationId":"getAccount","summary":"Read existing InstaVM credits, subscription and VM usage","security":[{"InstaVMKey":[]},{"InstaVMBearer":[]}],"responses":{"200":{"description":"Existing InstaVM account billing information.","content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"integer"},"billing_provider":{"const":"instavm"},"credit_dollars":{"type":["object","null"]},"subscription":{"type":["object","null"]},"vm_usage":{"type":["object","null"]}}}}}},"400":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request refused or upstream operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"InstaVMKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"InstaVMBearer":{"type":"http","scheme":"bearer","bearerFormat":"InstaVM API key"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"upstream_status":{"type":"integer"}}}}},"Run":{"type":"object","required":["id","status","tool","billing","poll_url"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","provisioning","preparing","running","completed","failed","interrupted"]},"tool":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"vm_id":{"type":"string"},"vm_name":{"type":"string"},"poll_url":{"type":"string"},"billing":{"type":"object","properties":{"provider":{"const":"instavm"},"mode":{"const":"existing_account"},"account_id":{"type":"integer"},"cleanup":{"type":"string","enum":["not_created","pending","confirmed"]},"vm_lifetime_seconds":{"type":"integer"}}},"result":{"type":"object","properties":{"stdout":{"type":"string"},"stderr":{"type":"string"},"exit_code":{"type":"integer"},"timed_out":{"type":"boolean"},"stdout_truncated":{"type":"boolean"},"stderr_truncated":{"type":"boolean"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"content_base64":{"type":"string","contentEncoding":"base64"},"size_bytes":{"type":"integer"},"error":{"type":"string"}}}}}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"upstream_status":{"type":"integer"}}}}},"RunRequest":{"type":"object","additionalProperties":false,"required":["tool"],"properties":{"tool":{"type":"string","description":"Exact catalog ID, such as sharkdp/hyperfine."},"args":{"type":"array","items":{"type":"string","maxLength":16384,"description":"Passed literally to the executable; no NUL bytes."},"maxItems":128,"default":[]},"stdin":{"type":"string","description":"UTF-8 input up to 128 KiB."},"files":{"type":"object","description":"At most 16 relative file paths; 512 KiB combined.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"object","required":["content_base64"],"additionalProperties":false,"properties":{"content_base64":{"type":"string","contentEncoding":"base64"}}}]},"maxProperties":16},"outputs":{"type":"array","items":{"type":"string"},"maxItems":16,"description":"Relative output file paths; 512 KiB combined."},"env":{"type":"object","additionalProperties":{"type":"string","maxLength":16384},"maxProperties":32},"timeout_seconds":{"type":"integer","minimum":1,"maximum":120,"default":30}}},"Tool":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"executable":{"type":"string"},"demo_command":{"type":"string"},"repository_url":{"type":"string"}}}}}}