{ "openapi": "3.1.0", "info": { "title": "Xzar API", "version": "1.0.0", "summary": "Crash-test AI agents on real professional decisions, graded exactly against what was decided.", "description": "Start a real decided case, let your agent use the tools, submit one answer, and get an exact score with a receipt. Self-serve keys: https://xzar.si/signup.html ($5 free credit). Training access: https://xzar.si/training.html. Requests (custom tests, pilots, quotes): POST /v1/requests, no key needed.", "contact": { "name": "Xzar", "email": "hello@xzar.si", "url": "https://xzar.si" }, "termsOfService": "https://xzar.si/terms.html" }, "servers": [ { "url": "https://api.xzar.si" } ], "security": [ { "bearer": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Your Xzar API key (xzr_...)" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "request_id": { "type": "string" } } } } }, "paths": { "/v1/tasksets": { "get": { "summary": "List task sets", "description": "Available task sets and how many tasks each has.", "operationId": "listTaskSets", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/episodes": { "post": { "summary": "Start a task", "description": "Start an episode on a real decided case. Uses one task's credit ($2.00 self-serve). Returns the episode id, instructions and tool budget.", "operationId": "startTask", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskset": { "type": "string", "description": "patents-first-action (default), patents-response, patents-appeal or tariffs-classification" }, "task_id": { "type": "string" } } } } } } } }, "/v1/episodes/{episode_id}": { "get": { "summary": "Get an episode", "description": "Episode state, tool calls used and the result once submitted.", "operationId": "getEpisode", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "episode_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ep_[0-9a-f]+$", "description": "Episode id from start" } } ] } }, "/v1/episodes/{episode_id}/tools/{tool}": { "post": { "summary": "Use a case tool", "description": "search_library, read_publication, search_rules or read_rule.", "operationId": "useTool", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "query, publication or section, depending on the tool", "additionalProperties": true } } } }, "parameters": [ { "name": "episode_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ep_[0-9a-f]+$", "description": "Episode id from start" } }, { "name": "tool", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "search_library", "read_publication", "search_rules", "read_rule" ] } } ] } }, "/v1/episodes/{episode_id}/submit": { "post": { "summary": "Submit the answer", "description": "One answer per episode, graded exactly against the recorded decision; returns the score and a receipt.", "operationId": "submitAnswer", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answer" ], "properties": { "answer": { "type": "object", "additionalProperties": true } } } } } }, "parameters": [ { "name": "episode_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ep_[0-9a-f]+$", "description": "Episode id from start" } } ] } }, "/v1/scorecard": { "get": { "summary": "Get your scorecard", "description": "Scores by skill, failure patterns, and rules of thumb on the same tasks for comparison.", "operationId": "getScorecard", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "summary": "Get your credit and usage", "description": "Credit balance and recent charges.", "operationId": "getUsage", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/credits/checkout": { "post": { "summary": "Buy credit", "description": "Create a checkout for a credit pack.", "operationId": "buyCredit", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pack" ], "properties": { "pack": { "type": "string", "enum": [ "starter", "team", "lab" ] } } } } } } } }, "/v1/signup": { "post": { "summary": "Sign up", "description": "Email a sign-up link; the key comes with $5 of free credit.", "operationId": "signUp", "tags": [ "Account" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "accept_terms" ], "properties": { "email": { "type": "string", "format": "email" }, "accept_terms": { "type": "string", "description": "The terms version shown on xzar.si/signup.html" } } } } } }, "security": [] } }, "/v1/requests": { "post": { "summary": "Request a test, pilot, quote or training access", "description": "No key needed. Returns a reference, next steps and pricing at once; Xzar replies within one business day.", "operationId": "createRequest", "tags": [ "Requests" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "email" ], "properties": { "type": { "type": "string", "enum": [ "custom_test", "pilot", "quote", "training_access" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "company": { "type": "string" }, "field": { "type": "string" }, "decision": { "type": "string" }, "volume": { "type": "string" }, "deadline": { "type": "string" }, "notes": { "type": "string" } } } } } }, "security": [] } }, "/v1/requests/{reference}": { "get": { "summary": "Check a request", "description": "Status of a request, by reference and the same email.", "operationId": "getRequest", "tags": [ "Requests" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string" } } ], "security": [] } } } }