{ "openapi": "3.1.0", "info": { "title": "SSBio Research API — CatShift", "description": "CatShift is under development. For now, please cite CatRange when using these results.", "version": "1.0.0" }, "servers": [ { "url": "https://api.sahassbio.com" } ], "paths": { "/catshift/v1/ready": { "get": { "tags": [ "CatShift service" ], "summary": "Catshift Ready", "description": "Public CatShift readiness and current limits, cached for at most five seconds.", "operationId": "catshift_ready_catshift_v1_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/catshift/v1/capabilities": { "get": { "tags": [ "CatShift service" ], "summary": "Catshift Capabilities", "description": "Public supported input modes, structure sources and bounded search controls.", "operationId": "catshift_capabilities_catshift_v1_capabilities_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/catshift/v1/stats": { "get": { "tags": [ "CatShift service" ], "summary": "Catshift Stats", "description": "Aggregate website/API searches, including demos; no submitted data or job IDs.", "operationId": "catshift_stats_catshift_v1_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/catshift/v1/jobs": { "post": { "tags": [ "CatShift searches" ], "summary": "Submit Catshift", "operationId": "submit_catshift_catshift_v1_jobs_post", "security": [ { "ResearchAPIKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "description": "Use the same key and inputs when retrying this intended CatShift search.", "title": "Idempotency-Key" }, "description": "Use the same key and inputs when retrying this intended CatShift search." } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_submit_catshift_catshift_v1_jobs_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "401": { "description": "Missing/invalid API key" }, "409": { "description": "Idempotency conflict or uncertain previous submission" }, "413": { "description": "Upload/request exceeds limit" }, "429": { "description": "Shared submission quota or request limit" }, "503": { "description": "Backend unavailable or submission uncertain" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/catshift/v1/jobs/{job_id}": { "get": { "tags": [ "CatShift searches" ], "summary": "Catshift Status", "description": "Poll an owned CatShift search. Suggested interval: ten seconds.", "operationId": "catshift_status_catshift_v1_jobs__job_id__get", "security": [ { "ResearchAPIKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/catshift/v1/jobs/{job_id}/results": { "get": { "tags": [ "CatShift searches" ], "summary": "Catshift Results", "description": "Ranked candidates, reference predictions and public limitations. Research preview.", "operationId": "catshift_results_catshift_v1_jobs__job_id__results_get", "security": [ { "ResearchAPIKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/catshift/v1/jobs/{job_id}/download": { "get": { "tags": [ "CatShift searches" ], "summary": "Catshift Download", "description": "Download the public result rows, including references and nonqualifying candidates.", "operationId": "catshift_download_catshift_v1_jobs__job_id__download_get", "security": [ { "ResearchAPIKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Public CatShift results CSV", "content": { "application/json": { "schema": {} }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/catshift/v1/jobs/{job_id}/notification-email": { "post": { "tags": [ "CatShift searches" ], "summary": "Catshift Notification", "description": "Add a notification email to your CatShift search after submission.", "operationId": "catshift_notification_catshift_v1_jobs__job_id__notification_email_post", "security": [ { "ResearchAPIKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationEmailRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_submit_catshift_catshift_v1_jobs_post": { "properties": { "mode": { "type": "string", "enum": [ "interactive", "csv", "demo" ], "title": "Mode", "default": "interactive" }, "options_json": { "type": "string", "title": "Options Json", "description": "JSON object: smiles; optional sequence/identifiers; structure_source upload, pdb or uniprot; accession, chain_id; direction up/down/either; min_abs_kcat_bin_shift 1–7 (default 3); max_candidates 19–190 (default 38); radius_angstrom 2–20 (default 12); region_selection automatic/custom, region_ids, custom_region_residues, catalytic_residues, binding_residues, protect_functional_residues and email. Demo needs no reference inputs. No structure generation.", "default": "{}" }, "structure_file": { "anyOf": [ { "type": "string", "contentMediaType": "application/octet-stream" }, { "type": "null" } ], "title": "Structure File", "description": "Nonempty UTF-8 PDB or mmCIF (.pdb/.cif/.mmcif), at most 5 MiB. Interactive upload mode only." }, "csv_file": { "anyOf": [ { "type": "string", "contentMediaType": "application/octet-stream" }, { "type": "null" } ], "title": "Csv File", "description": "UTF-8 CSV within 64 KiB, 1–5 reference rows. Bulk rows require structure_source pdb/uniprot, accession and smiles; optional sequence, sequence_id, substrate_id and chain_id." } }, "type": "object", "title": "Body_submit_catshift_catshift_v1_jobs_post" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "JobResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Full UUID; accessible only with a key for its submitting principal." }, "status": { "type": "string", "title": "Status" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url" }, "results_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Results Url" } }, "additionalProperties": true, "type": "object", "required": [ "job_id", "status" ], "title": "JobResponse" }, "NotificationEmailRequest": { "properties": { "email": { "type": "string", "maxLength": 320, "minLength": 3, "title": "Email" } }, "additionalProperties": false, "type": "object", "required": [ "email" ], "title": "NotificationEmailRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "ResearchAPIKey": { "type": "http", "description": "Private API key issued by SSBio. Send Authorization: Bearer YOUR_KEY.", "scheme": "bearer" } } } }