{ "openapi": "3.0.3", "info": { "title": "PlasmidAgent API", "version": "0.2.0", "description": "Workspace-scoped plasmid analysis platform. Scientific results and billing are simulated in this release. Upload files before submitting. External file URLs and callbacks are rejected. Clerk organization sessions and workspace API keys are accepted. Administrative operations require a Clerk admin session." }, "servers": [ { "url": "https://api.plasmidagent.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/workspace": { "get": { "operationId": "getWorkspace", "summary": "getWorkspace", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/v1/analyses": { "get": { "operationId": "listAnalyses", "summary": "listAnalyses", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Analysis" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "data", "next_cursor" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "sample_id", "in": "query", "schema": { "type": "string" } }, { "name": "batch_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] }, "post": { "operationId": "createAnalysis", "summary": "createAnalysis", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analysis" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisCreate" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/v1/analyses/{analysis_id}": { "get": { "operationId": "getAnalysis", "summary": "getAnalysis", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisDetail" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteAnalysis", "summary": "deleteAnalysis", "responses": { "204": { "description": "No content" }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." }, "parameters": [ { "name": "analysis_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/analyses/{analysis_id}/result": { "get": { "operationId": "getAnalysisResult", "summary": "getAnalysisResult", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResult" } }, "text/html": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } }, "parameters": [ { "name": "analysis_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/uploads": { "get": { "operationId": "listUploads", "summary": "listUploads", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "data", "next_cursor" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] }, "post": { "operationId": "createUpload", "summary": "createUpload", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "format": { "type": "string", "enum": [ "fasta", "fastq", "fastq.gz", "ab1" ] } }, "required": [ "file", "format" ] } } } } } }, "/v1/uploads/{upload_id}": { "delete": { "operationId": "deleteUpload", "summary": "deleteUpload", "responses": { "204": { "description": "No content" }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." }, "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/uploads/{upload_id}/content": { "get": { "operationId": "downloadUpload", "responses": { "200": { "description": "Private uploaded file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/api-keys": { "get": { "operationId": "listAPIKeys", "summary": "listAPIKeys", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } } }, "required": [ "data" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." }, "post": { "operationId": "createAPIKey", "summary": "createAPIKey", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "record": { "$ref": "#/components/schemas/APIKey" } }, "required": [ "key", "record" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } } } }, "/v1/api-keys/{key_id}": { "delete": { "operationId": "revokeAPIKey", "summary": "revokeAPIKey", "responses": { "204": { "description": "No content" }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." }, "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "getUsage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive UTC date. Defaults to the last 30 days. Maximum range 366 days." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive UTC date. Defaults to the last 30 days. Maximum range 366 days." } ] } }, "/v1/billing": { "get": { "operationId": "getBilling", "summary": "getBilling", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." }, "patch": { "operationId": "changeBillingMode", "summary": "changeBillingMode", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "prepaid", "postpaid" ] } }, "required": [ "mode" ] } } } } } }, "/v1/billing/checkout": { "post": { "operationId": "createCheckout", "summary": "createCheckout", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100 } }, "required": [ "mode" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/v1/billing/portal": { "post": { "operationId": "createBillingPortal", "summary": "createBillingPortal", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." } }, "/v1/billing/postpaid-request": { "post": { "operationId": "requestPostpaid", "summary": "requestPostpaid", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation." } }, "/v1/billing/test-credits": { "post": { "operationId": "grantTestCredits", "summary": "grantTestCredits", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "description": "Requires a workspace admin Clerk session. API keys cannot perform this operation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/healthz": { "get": { "operationId": "health", "summary": "health", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "pipeline": { "type": "string" } }, "required": [ "status", "pipeline" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/openapi.json": { "get": { "operationId": "openapi", "summary": "openapi", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Clerk organization session token or pa_test_ workspace API key. Never put credentials in a URL." } }, "parameters": { "AnalysisId": { "name": "analysis_id", "in": "path", "required": true, "schema": { "type": "string" } } }, "responses": { "Error": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "AnalysisStatus": { "type": "string", "enum": [ "queued", "analysing", "completed", "failed" ] }, "AnalysisCreate": { "type": "object", "additionalProperties": false, "required": [ "sample_id", "reads" ], "properties": { "sample_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "batch_id": { "type": "string", "maxLength": 200 }, "reads": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/InputFile" } }, "reference": { "allOf": [ { "$ref": "#/components/schemas/InputFile" } ], "nullable": true, "description": "Optional FASTA reference." }, "callback_url": { "type": "string", "format": "uri", "description": "Reserved. Supplied callbacks are rejected in this version." } } }, "InputFile": { "type": "object", "additionalProperties": false, "required": [ "format" ], "properties": { "upload_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Only this application's authenticated upload content URLs are supported." }, "format": { "type": "string", "enum": [ "fasta", "fastq", "fastq.gz", "ab1" ] }, "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" } }, "oneOf": [ { "required": [ "upload_id" ], "not": { "required": [ "url" ] } }, { "required": [ "url" ], "not": { "required": [ "upload_id" ] } } ] }, "Analysis": { "type": "object", "properties": { "analysis_id": { "type": "string", "format": "uuid" }, "sample_id": { "type": "string" }, "batch_id": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/AnalysisStatus" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "pipeline_version": { "type": "string" }, "is_simulated": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "pass", "review", "fail", null ], "nullable": true }, "input_bytes": { "type": "integer", "minimum": 0 }, "attempt_count": { "type": "integer", "minimum": 0 }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "required": [ "analysis_id", "sample_id", "batch_id", "status", "created_at", "updated_at", "started_at", "completed_at", "pipeline_version", "is_simulated", "verdict", "input_bytes", "attempt_count", "error" ] }, "AnalysisResult": { "type": "object", "properties": { "analysis_id": { "type": "string", "format": "uuid" }, "sample_id": { "type": "string" }, "verdict": { "type": "string", "enum": [ "pass", "review", "fail" ] }, "pipeline_version": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/Check" } }, "is_simulated": { "type": "boolean" }, "note": { "type": "string" }, "processing": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "nullable": true }, "reads": { "type": "integer", "minimum": 0, "nullable": true }, "bases": { "type": "integer", "minimum": 0, "nullable": true } }, "required": [ "bytes", "reads", "bases" ] }, "provider_usage": { "type": "array", "items": { "type": "object", "description": "Actual per-attempt provider usage when available. Always empty in stub mode." } } }, "required": [ "analysis_id", "sample_id", "verdict", "pipeline_version", "completed_at", "checks", "is_simulated", "note", "processing", "provider_usage" ] }, "Check": { "type": "object", "required": [ "name", "category", "status", "summary" ], "properties": { "name": { "type": "string" }, "category": { "type": "string", "enum": [ "identity", "integrity", "contamination" ] }, "status": { "type": "string", "enum": [ "pass", "flag", "fail" ] }, "summary": { "type": "string" }, "value": {}, "unit": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } }, "Upload": { "type": "object", "properties": { "upload_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "format": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string" }, "url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "upload_id", "name", "format", "size_bytes", "sha256", "url", "created_at", "deleted_at" ] }, "AnalysisDetail": { "allOf": [ { "$ref": "#/components/schemas/Analysis" }, { "type": "object", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/Upload" } }, "reference_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "inputs", "reference_id" ] } ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "clerk_org_id": { "type": "string" }, "is_admin": { "type": "boolean" }, "is_simulated": { "type": "boolean" }, "billing_ready": { "type": "boolean" }, "max_file_bytes": { "type": "integer", "minimum": 0 }, "max_analysis_bytes": { "type": "integer", "minimum": 0 }, "unit_price_pence": { "type": "integer", "minimum": 0 } }, "required": [ "id", "name", "clerk_org_id", "is_admin", "is_simulated", "billing_ready", "max_file_bytes", "max_analysis_bytes", "unit_price_pence" ] }, "APIKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "name", "prefix", "created_at", "last_used_at", "revoked_at" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 }, "amount_pence": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "refunded_pence": { "type": "integer", "minimum": 0 }, "paid_amount_pence": { "type": "integer", "minimum": 0, "nullable": true, "description": "Actual paid amount including any Checkout tax. Null for free grants." } }, "required": [ "id", "mode", "quantity", "amount_pence", "currency", "completed_at", "refunded_pence", "paid_amount_pence" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "amount_pence": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "hosted_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "status", "amount_pence", "currency", "hosted_url", "created_at" ] }, "Billing": { "type": "object", "properties": { "is_simulated": { "type": "boolean" }, "postpaid_approved": { "type": "boolean" }, "card_verified": { "type": "boolean" }, "sandbox_access": { "type": "boolean" }, "payment_blocked": { "type": "boolean" }, "stripe_configured": { "type": "boolean" }, "postpaid_integration_verified": { "type": "boolean" }, "unit_price_pence": { "type": "integer", "minimum": 0 }, "credits": { "type": "integer", "minimum": 0 }, "credits_reserved": { "type": "integer", "minimum": 0 }, "credits_available": { "type": "integer", "minimum": 0 }, "unpaid_pence": { "type": "integer", "minimum": 0 }, "reserved_pence": { "type": "integer", "minimum": 0 }, "postpaid_limit_pence": { "type": "integer", "minimum": 0 }, "currency": { "type": "string" }, "mode": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "postpaid_requested_at": { "type": "string", "format": "date-time", "nullable": true }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } }, "required": [ "is_simulated", "postpaid_approved", "card_verified", "sandbox_access", "payment_blocked", "stripe_configured", "postpaid_integration_verified", "unit_price_pence", "credits", "credits_reserved", "credits_available", "unpaid_pence", "reserved_pence", "postpaid_limit_pence", "currency", "mode", "postpaid_requested_at", "payments", "invoices" ] }, "Usage": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "submitted": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 }, "running": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "simulated_completed": { "type": "integer", "minimum": 0 }, "uploaded_bytes": { "type": "integer", "minimum": 0 }, "submitted_bytes": { "type": "integer", "minimum": 0 }, "real_processed_bytes": { "type": "integer", "minimum": 0 }, "real_processed_reads": { "type": "integer", "minimum": 0 }, "real_processed_bases": { "type": "integer", "minimum": 0 }, "average_duration_seconds": { "type": "number", "nullable": true }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "submitted": { "type": "integer", "minimum": 0 }, "completed": { "type": "integer", "minimum": 0 } }, "required": [ "date", "submitted", "completed" ] } }, "financial": { "type": "object", "nullable": true, "properties": { "test_credits_used": { "type": "integer", "minimum": 0 }, "test_postpaid_pence": { "type": "integer", "minimum": 0 }, "test_postpaid_invoiced_pence": { "type": "integer", "minimum": 0 }, "test_postpaid_paid_pence": { "type": "integer", "minimum": 0 }, "test_purchases_pence": { "type": "integer", "minimum": 0 } }, "required": [ "test_credits_used", "test_postpaid_pence", "test_postpaid_invoiced_pence", "test_postpaid_paid_pence", "test_purchases_pence" ] } }, "required": [ "from", "to", "submitted", "completed", "running", "failed", "simulated_completed", "uploaded_bytes", "submitted_bytes", "real_processed_bytes", "real_processed_reads", "real_processed_bases", "average_duration_seconds", "daily", "financial" ] } } } }