{ "openapi": "3.1.0", "info": { "contact": { "url": "https://support.collaborativedrug.com/hc/en-us/requests/new" }, "description": "Collaborative Drug Discovery provides an API (Application Programming\nInterface) that can be used for secure programmatic access to your vault\ndata. Using the API, client applications such as Microsoft Office, Pipeline\nPilot, Knime and others can be configured to directly access and process\nchemical and biological data from CDD Vault.\n\n**Download the full specification:** [OpenAPI YAML](cdd_openapi.yaml) ·\n[OpenAPI JSON](cdd_openapi.json). Import it into Postman, an SDK/client\ngenerator, or your IDE.\n\n\n**For LLMs / AI tools:** [llms.txt](llms.txt) (concise index) ·\n[llms-full.txt](llms-full.txt) (full documentation text).\n\n## Using the API\n\nThe API is designed using RESTful principles: objects (resources) are\nidentified by URLs, and actions are specified by HTTP verbs. (If that doesn't\nmean anything to you, don't worry — it isn't necessary for using the API.)\nAPI URLs closely mirror the URLs of the web application.\n\nAs in the web application, access to data is scoped by vault, so most API\nURLs contain a vault identifier. The majority of API calls return a JSON\nstructure as the response body.\n\n## Object IDs\n\nVaults, saved searches, and other objects are identified by an integer ID.\nWhen you retrieve a list of objects (vaults, saved searches, projects, etc.)\neach object has both a name and an ID, and you typically supply the numeric\nID in subsequent calls. Some parameters take lists of objects, expressed as a\ncomma-separated list of IDs.\n\nThe same IDs appear in the web interface URLs, so you can often copy a number\nfrom the browser into an API call:\n\n- Browser: `https://app.collaborativedrug.com/vaults/4657/searches`\n- API: `https://app.collaborativedrug.com/api/v1/vaults/4657/searches`\n\n## Authentication & security\n\nEvery request must include your API key in the `X-CDD-Token` header, and all\nrequests must be made over HTTPS so the token and data are encrypted in\ntransit.\n\nAccess is controlled at several levels:\n\n- **Token** — tokens are issued per user/account and carry a role (set of\n capabilities); the effective capabilities depend on the token owner's role\n in the vault(s) being accessed. See the support site for how to obtain a\n token.\n- **Vault** — even with a valid token, data is only available from vaults\n that have API access enabled. A vault administrator can request this by\n emailing CDD Support.\n- **Project** — a user can only access data in projects they have permission\n for. The projects a user can access in a vault can be listed via the API.\n\n## POST `/query` endpoints\n\nMost list and read endpoints accept their parameters either as URL query\nparameters on the `GET` request, or as a JSON body on a companion `POST`\nrequest at the same path with `/query` appended (for example\n`POST /molecules/query` instead of `GET /molecules`). The `/query` form\nexists because many HTTP client libraries cannot send a body with a `GET`\nrequest, and because long or complex filters are easier to express as JSON.\nThe two forms accept the same parameters and return the same responses; the\n`POST /query` form is recommended for anything beyond a trivial request.\n\n## Pagination\n\nList endpoints are paginated. Use `page_size` to set the number of records\nper page (default 50, maximum 1000 for synchronous requests) and `offset` to\nskip records. Paginated responses include the total `count` alongside the\nreturned `objects`. To page through a large result set, increase `offset` by\n`page_size` until you have retrieved `count` records.\n\n## Asynchronous requests (async=true)\n\nFor large result sets, pass async=true to a query endpoint. Instead of\nreturning the data inline, the request creates an export and returns its\ndetails (including an export id). Asynchronous exports allow a larger\n`page_size` (up to 10000). Poll `GET /export_progress/{export_id}` until the\nexport reports that it is finished, then download the result from\n`GET /exports/{export_id}`. `GET /exports` lists all of your in-progress\nexports (including those started from the web application).\n\n## Rate limits and throttling\n\nCDD Vault does not limit the total number of API requests you can make, but\nit does throttle usage in two ways. Please optimize your integrations to use\nthe API efficiently, and contact CDD Support if any limit poses a problem.\n\n- **3 concurrent requests.** Each user may have up to 3 requests in flight at\n once, so an integration can use up to 3 threads/processes that each issue a\n new request as soon as the previous one completes. This limit is per\n **user**, not per API key — important if you run multiple integrations.\n- **30 queued exports.** Every request that uses `async=true` (and every\n saved-search download) launches a background export. Up to 3 run at a time\n and the rest queue, up to a maximum of 30 queued exports.\n\nUse of the API is monitored; abuse may result in suspension of access and\nfurther investigation.\n", "license": { "name": "Proprietary", "url": "https://support.collaborativedrug.com/hc/en-us/requests/new" }, "title": "CDD API", "version": "1.0.0" }, "servers": [ { "url": "https://app.collaborativedrug.com/api/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "description": "Track asynchronous API request executions", "name": "API Executions" }, { "description": "Asynchronous batch move jobs", "name": "Batch Move Jobs" }, { "description": "Batches handling", "name": "Batches" }, { "description": "Collections of molecules", "name": "Collections" }, { "description": "Control well layouts for protocols and runs", "name": "Control Layouts" }, { "description": "Public and vault datasets", "name": "Datasets" }, { "description": "Deep learning bioisostere suggestions", "name": "Deep Learning Bioisosteres" }, { "description": "Deep learning molecular similarity", "name": "Deep Learning Similarity" }, { "description": "Protocol dose response calculations management", "name": "Dose Response Calculations" }, { "description": "Dose response data series management", "name": "Dose Response Data Series" }, { "description": "Electronic lab notebook entries", "name": "ELN Entries" }, { "description": "Asynchronous data exports", "name": "Exports" }, { "description": "Vault field definitions", "name": "Fields" }, { "description": "File attachments", "name": "Files" }, { "description": "Import parsers for structured data files", "name": "Import Parsers" }, { "description": "Sample inventory locations", "name": "Inventory" }, { "description": "Inventory samples and their events", "name": "Inventory Samples" }, { "description": "Import mapping templates", "name": "Mapping Templates" }, { "description": "Molecules handling", "name": "Molecules" }, { "description": "Plates of wells", "name": "Plates" }, { "description": "Projects within a vault", "name": "Projects" }, { "description": "Protocols and their readout data", "name": "Protocols" }, { "description": "Rows of protocol readout data", "name": "Readout Rows" }, { "description": "Registration forms", "name": "Registration Forms" }, { "description": "Registration systems", "name": "Registration Systems" }, { "description": "Runs of protocol data", "name": "Runs" }, { "description": "Saved searches", "name": "Searches" }, { "description": "Data import jobs (slurps)", "name": "Slurps" }, { "description": "Vault operational status", "name": "Status" }, { "description": "Users management", "name": "Users" }, { "description": "Vaults management", "name": "Vaults" } ], "paths": { "/vaults": { "get": { "description": "Return a list of accessible vaults", "operationId": "get_vaults", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "id": { "example": 489978881, "type": "integer" }, "name": { "example": "McKerrow Vault", "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "List of vaults" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "List of vaults", "tags": [ "Vaults" ] } }, "/vaults/{vault_id}/fields": { "get": { "description": "Get all the fields both internal and user defined\n", "operationId": "getFields", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/fields" }, "type": "array" } } }, "description": "List of all fields" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Retrieve all fields", "tags": [ "Fields" ] } }, "/vaults/{vault_id}/fields/{field_id}/pick_list_values": { "get": { "description": "List the pick list values for a vault field definition.", "operationId": "getPickListValues", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the field definition", "in": "path", "name": "field_id", "required": true, "schema": { "type": "integer" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "objects": { "items": { "$ref": "#/components/schemas/pick_list_value_object" }, "type": "array" }, "offset": { "type": "integer" }, "page_size": { "type": "integer" } }, "required": [ "count", "objects" ], "type": "object" } } }, "description": "A page of pick list values" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get pick list values", "tags": [ "Fields" ] }, "post": { "description": "Create a pick list value on a field definition. Requires vault administrator access.", "operationId": "createPickListValue", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the field definition", "in": "path", "name": "field_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pick_list_value_write" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pick_list_value_object" } } }, "description": "The created pick list value" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Create a pick list value", "tags": [ "Fields" ] } }, "/vaults/{vault_id}/fields/{field_id}/pick_list_values/{id}": { "delete": { "description": "Delete a pick list value. Requires vault administrator access.", "operationId": "deletePickListValue", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the field definition", "in": "path", "name": "field_id", "required": true, "schema": { "type": "integer" } }, { "description": "Numeric identifier of the pick list value", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } }, "description": "The pick list value was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Pick list value not found, or vault is unauthorized" } }, "summary": "Delete a pick list value", "tags": [ "Fields" ] }, "get": { "description": "Retrieve a single pick list value.", "operationId": "getPickListValue", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the field definition", "in": "path", "name": "field_id", "required": true, "schema": { "type": "integer" } }, { "description": "Numeric identifier of the pick list value", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pick_list_value_object" } } }, "description": "The pick list value" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Pick list value not found, or vault is unauthorized" } }, "summary": "Get a pick list value", "tags": [ "Fields" ] }, "put": { "description": "Update a pick list value. Requires vault administrator access.", "operationId": "updatePickListValue", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the field definition", "in": "path", "name": "field_id", "required": true, "schema": { "type": "integer" } }, { "description": "Numeric identifier of the pick list value", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pick_list_value_write" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pick_list_value_object" } } }, "description": "The updated pick list value" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Pick list value not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update a pick list value", "tags": [ "Fields" ] } }, "/vaults/{vault_id}/api_executions": { "get": { "description": "Return the API usage (both async and sync) in seconds between a particular timeframe. Use after and before parameters to specify a date range. By default and if before is used with no after, the previous 30 days are returned. The time returned is for the current API key only.", "operationId": "get_api_executions", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Start of the date range (YYYY-MM-DDThh:mm:ss±hh:mm). Defaults to 30 days before `before` when omitted.", "in": "query", "name": "after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of the date range (YYYY-MM-DDThh:mm:ss±hh:mm). Defaults to the current date and time when omitted.", "in": "query", "name": "before", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "properties": { "after": { "description": "Start of the measured range.", "example": "2023-01-01T07:00:00.000Z", "format": "date-time", "type": "string" }, "before": { "description": "End of the measured range. Only present when the `before` query parameter was supplied on the request.", "example": "2023-01-22T08:12:34.000Z", "format": "date-time", "type": "string" }, "seconds": { "description": "Total API time used in the range, in seconds.", "example": 20.3, "type": "number" } }, "type": "object" }, "description": "A single-entry object whose key is the name of the API key used for the request (it is the key's name, not a fixed field called `api-key-name`).", "example": { "My API key": { "after": "2023-01-01T07:00:00.000Z", "before": "2023-01-22T08:12:34.000Z", "seconds": 20.3 } }, "type": "object" } } }, "description": "API usage data" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "API usage in seconds", "tags": [ "API Executions" ] } }, "/vaults/{vault_id}/batch_move_jobs": { "get": { "description": "Get all batch move jobs. Requires the user to be a vault administrator.", "operationId": "get_all_batch_move_jobs", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/batch_move_job" }, "type": "array" } } }, "description": "List of all batch move jobs" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get all batch move jobs", "tags": [ "Batch Move Jobs" ] }, "post": { "description": "Create a batch move job to move a batch to a different molecule in the same vault. Requires the user to be a vault administrator.", "operationId": "create_batch_move_job", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch_move_job_create" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch_move_job" } } }, "description": "Batch move job created" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Create a new batch move job", "tags": [ "Batch Move Jobs" ] } }, "/vaults/{vault_id}/batch_move_jobs/{job_id}": { "delete": { "description": "Cancel a single batch move job. Once a job has started it can no longer be canceled. Requires the user to be a vault administrator.", "operationId": "cancel_batch_move_job", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "job_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch_move_job" } } }, "description": "Batch move job canceled" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch_move_job" } } }, "description": "The job is no longer in a cancelable state (it has already started or finished). The current job is returned unchanged." } }, "summary": "Cancel a single batch move job", "tags": [ "Batch Move Jobs" ] }, "get": { "description": "Retrieve a single batch move job. Requires the user to be a vault administrator.", "operationId": "get_single_batch_move_job", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "job_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch_move_job" } } }, "description": "Batch move job details" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Retrieve a single batch move job", "tags": [ "Batch Move Jobs" ] } }, "/vaults/{vault_id}/batches": { "post": { "description": "The body of the POST must contain a JSON structure specifying the molecule attributes. The structure is roughly the same format as what is returned by a GET call but with some restrictions and additions.\nNote that in a registration vault, POST batch is the only way to create a new molecule, since the registration of a new molecule must be accompanied by a first batch. In this case, the JSON describing the batch will include a \"molecule\" field with detailed information on the new molecule.\n", "operationId": "createBatch", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/batch_create" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Create a batch", "tags": [ "Batches" ] } }, "/vaults/{vault_id}/batches/query": { "post": { "description": "Get the information from multiple batches. We still support the now deprecated GET queries on the enpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.", "operationId": "getBatches", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/batch_query" }, { "$ref": "#/components/schemas/batch_query_only_id" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/batch" }, "type": "array" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get multiple batches", "tags": [ "Batches" ] } }, "/vaults/{vault_id}/batches/{batch_id}": { "get": { "description": "Get the information about a single batch", "operationId": "getBatch", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "batch_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get a single batch", "tags": [ "Batches" ] }, "put": { "description": "See Create for valid fields. (An exception to this is the Molecule field - this PUT Batches call should not be used to update the chemical structure of the parent Molecule - use the PUT Molecules API call to achieve this.) Fields not specified in the JSON are not changed.\n\nTo delete a Batch, simply submit with an empty projects array. (For safety/security purposes, Batches which have data associated with them cannot be deleted via this PUT Batches API call. Data (such as rows of readout data in a Protocol Run) must be removed prior to using the PUT Batches API call to delete a Batch.)\n\nNote that the ID for the batch is specified as part of the URL, not in the JSON (the JSON can contain an ID field as long as its value matches the URL).\n", "operationId": "updateBatch", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "batch_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/batch_create" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/batch" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Update a batch", "tags": [ "Batches" ] } }, "/vaults/{vault_id}/collections": { "post": { "description": "Create a collection, the name should be unique unless you want to overwrite an existing collection.\n", "operationId": "createCollection", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/collection_create" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/collection" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Create a collection", "tags": [ "Collections" ] } }, "/vaults/{vault_id}/collections/query": { "post": { "description": "Get the information from multiple collections. We still support the now deprecated GET queries on the enpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.\n", "operationId": "getCollections", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/collections_query" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/collection" }, "type": "array" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get multiple collections", "tags": [ "Collections" ] } }, "/vaults/{vault_id}/collections/{collection_id}": { "delete": { "description": "Delete a collection. The molecules in the collection are not affected.", "operationId": "deleteCollection", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the collection", "in": "path", "name": "collection_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } }, "description": "The collection was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Collection not found, or vault is unauthorized" } }, "summary": "Delete a collection", "tags": [ "Collections" ] }, "get": { "description": "Get the information about a single collection", "operationId": "getCollection", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/collection" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get a single collection", "tags": [ "Collections" ] }, "put": { "description": "", "operationId": "updateCollection", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/collection_update" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/collection" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Update a collection", "tags": [ "Collections" ] } }, "/vaults/{vault_id}/control_layouts": { "get": { "description": "List the control layouts in the vault. Supports pagination via `page_size` and `offset`, and the usual `created_after`/`modified_after` filters.", "operationId": "getControlLayouts", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "If true, run the listing as an asynchronous export.", "in": "query", "name": "async", "schema": { "type": "boolean" } }, { "description": "If true, return only the ids of the matching control layouts.", "in": "query", "name": "only_ids", "schema": { "type": "boolean" } }, { "description": "Comma-separated project ids to filter by.", "in": "query", "name": "projects", "schema": { "type": "string" } }, { "description": "Only include layouts created on or after this time.", "in": "query", "name": "created_after", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include layouts created on or before this time.", "in": "query", "name": "created_before", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include layouts modified on or after this time.", "in": "query", "name": "modified_after", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include layouts modified on or before this time.", "in": "query", "name": "modified_before", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "objects": { "items": { "$ref": "#/components/schemas/control_layout" }, "type": "array" }, "offset": { "type": "integer" }, "page_size": { "type": "integer" } }, "required": [ "count", "objects" ], "type": "object" } } }, "description": "A page of control layouts" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get control layouts", "tags": [ "Control Layouts" ] }, "post": { "description": "Create a control layout for a protocol or run. The layout dimensions are set with either `size` or `plate`, and the target with either `protocol` or `run`.", "operationId": "createControlLayout", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/control_layout_create" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/control_layout" } } }, "description": "The created control layout" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Create a control layout", "tags": [ "Control Layouts" ] } }, "/vaults/{vault_id}/control_layouts/{id}": { "delete": { "description": "Delete a control layout.", "operationId": "deleteControlLayout", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the control layout", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The control layout was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Control layout not found, or vault is unauthorized" } }, "summary": "Delete a control layout", "tags": [ "Control Layouts" ] }, "get": { "description": "Retrieve a single control layout.", "operationId": "getControlLayout", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the control layout", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/control_layout" } } }, "description": "The control layout" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Control layout not found, or vault is unauthorized" } }, "summary": "Get a control layout", "tags": [ "Control Layouts" ] } }, "/vaults/{vault_id}/data_sets": { "get": { "description": "List datasets", "operationId": "getDatasets", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/data_set" }, "type": "array" } } }, "description": "Success" }, "404": { "description": "Unauthorized or not found" } }, "summary": "Get dataset", "tags": [ "Datasets" ] } }, "/vaults/{vault_id}/eln/entries": { "post": { "description": "The body of the POST must contain a JSON structure specifying the desired ELN entry attributes.\n\nNote: Files may be inserted into existing ELN entries using the POST Files API call.\n", "operationId": "createELN", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/eln_create" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eln_entry_status" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Create an ELN entry", "tags": [ "ELN Entries" ] } }, "/vaults/{vault_id}/eln/entries/query": { "post": { "description": "Returns a summary of all available ELN entries for the Vault specified if async=false (default).\nIf async=true, returns a zip file containing the export of all available ELN entries.\n\nFor security purposes, the GET and POST ELN Entries CDD Vault API commands documented here are only available for Vault Administrators.\n", "operationId": "getElnEntries", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/eln_entries_query" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/eln_entry_status" }, "type": "array" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get all or some ELN entries", "tags": [ "ELN Entries" ] } }, "/vaults/{vault_id}/eln/entries/{id}": { "put": { "description": "Update an existing ELN entry. Only the attributes supplied in the body are changed. Content supplied in `append_to_body` (text, links, files) is appended to the existing entry body.\n", "operationId": "updateELN", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the ELN entry", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eln_create" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eln_entry_status" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "ELN entry not found, or vault is unauthorized" } }, "summary": "Update an ELN entry", "tags": [ "ELN Entries" ] } }, "/vaults/{vault_id}/eln/entries/{id}/status": { "post": { "description": "Perform a witnessing/status action on an ELN entry (submit, approve, reject, cancel, reopen, finalize, or discard). Requires vault administrator access and write permission. The valid actions depend on whether ELN witnessing is enabled for the vault.", "operationId": "elnEntryStatusAction", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the ELN entry", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eln_status_action" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/eln_entry_status" } } }, "description": "The updated ELN entry" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Invalid or missing status_action" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "ELN entry (or witness) not found, or vault is unauthorized" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The entry cannot transition from its current status" } }, "summary": "Perform an ELN entry status action", "tags": [ "ELN Entries" ] } }, "/vaults/{vault_id}/export_progress/{export_id}": { "get": { "description": "Check on the status of your export task. Repeat this call every 5-10 seconds (suggested interval) until the status is “finished”", "operationId": "export_progress", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "description": "Numeric identifier of the export", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export" } } }, "description": "Successful operation" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "default": "Couldn't find export with 'id'={export_id}" } }, "type": "object" } } }, "description": "Couldn't find this export" } }, "summary": "Get progress of an export", "tags": [ "Exports" ] } }, "/vaults/{vault_id}/exports": { "get": { "description": "Check how many async API export tasks are currently running and see the current status of the user's queue. The endpoint does not accept any normal API parameters and lists all of a user's exports, including any exports initiated via the GUI/front-end. Note: This GET Exports API call will return ALL exports across all Vaults applicable to the API Token specified, regardless of the Vault ID used in the API url.\n", "operationId": "check_all_exports", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/exports" } } }, "description": "List of all active exports" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Check All Current Exports", "tags": [ "Exports" ] } }, "/vaults/{vault_id}/exports/{export_id}": { "delete": { "description": "Cancels an export if possible", "operationId": "cancel_export", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "description": "Numeric identifier of the export", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export" } } }, "description": "The export was canceled (its `status` becomes `canceled`)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "405": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export" } } }, "description": "The export was not in a cancelable state (for example it has already finished or was already canceled). The export's current state is returned unchanged." } }, "summary": "Cancel Export", "tags": [ "Exports" ] }, "get": { "description": "Retrieve the output of an export once it is ready. An export is created whenever a query endpoint is called with async=true (for example `POST /molecules/query`, `POST /batches/query`, or an ELN entries query), as well as when running a saved search. This single endpoint returns the finished output for any of them. If the export is not finished it returns `403` together with the export's async progress details; poll `GET /export_progress/{export_id}` until it is ready. The output format (JSON, CSV, SDF, etc.) depends on the format requested when the export was created.\n\nDepending on server configuration the file may be served directly (`200`) or via a `302` redirect to a temporary download URL (e.g. S3). Configure your client to follow redirects — with curl, pass `-L`.", "operationId": "exports", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "description": "Numeric identifier of the export", "type": "integer" } } ], "responses": { "200": { "description": "Successful operation; the response body is the export file. The format depends on what was requested when the export was created (JSON, CSV, SDF, etc.)." }, "302": { "description": "Redirect to a temporary download URL for the file (used when files are served directly from S3). Follow the `Location` header (curl: `-L`).", "headers": { "Location": { "description": "Temporary URL to download the export file from.", "schema": { "type": "string" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export" } } }, "description": "The export is not ready yet" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "default": "Couldn't find export with 'id'={export_id}" } }, "type": "object" } } }, "description": "Couldn't find this export" } }, "summary": "Get the output of an export", "tags": [ "Exports" ] } }, "/vaults/{vault_id}/files": { "post": { "description": "Attach a file to a record in the vault. The request must be sent as `multipart/form-data` (the file itself is the `file` part; the `resource_class` and `resource_id` fields identify the record to attach it to).\n\nFiles can only be attached to the four resource classes listed under `resource_class`: `run`, `molecule`, `protocol`, and `eln_entry`. Readout rows are not directly attachable — there is no `readout_row` resource class. To associate a file with protocol readout data, attach it to the parent `run` (`resource_class: run`, `resource_id`: the run's id) or to the `protocol`.\n", "operationId": "attachFile", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "Path to the file to be uploaded", "format": "binary", "type": "string" }, "resource_class": { "description": "Class of the resource to which the file is attached", "enum": [ "run", "molecule", "protocol", "eln_entry" ], "type": "string" }, "resource_id": { "description": "Unique identifier of the resource to which the file is attached", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Internal file ID", "type": "string" }, "name": { "description": "Name of the file", "type": "string" } }, "type": "object" } } }, "description": "File successfully attached" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Attach a file to an object", "tags": [ "Files" ] } }, "/vaults/{vault_id}/files/{file_id}": { "delete": { "description": "Delete a file", "operationId": "deleteFile", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "file_id", "required": true, "schema": { "description": "Numeric identifier of the file", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/file" } } }, "description": "The file" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Delete file", "tags": [ "Files" ] }, "get": { "description": "Return a single file with the content base64 encoded.\n", "operationId": "getFile", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "file_id", "required": true, "schema": { "description": "Numeric identifier of the file", "type": "integer" } } ], "responses": { "200": { "description": "Successful operation, output will depend on format selected when doing the query" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "default": "Couldn't find file with 'id'={file_id}" } }, "type": "object" } } }, "description": "Couldn't find this file" } }, "summary": "Retrieve a file", "tags": [ "Files" ] } }, "/vaults/{vault_id}/import_parsers": { "get": { "description": "List the import parsers (structured-file parsing templates) defined in the vault. The listing returns summary fields only; use the show endpoint to retrieve a parser's full `template_json` configuration.", "operationId": "getImportParsers", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "objects": { "items": { "$ref": "#/components/schemas/import_parser" }, "type": "array" } }, "required": [ "count", "objects" ], "type": "object" } } }, "description": "List of import parsers" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get import parsers", "tags": [ "Import Parsers" ] } }, "/vaults/{vault_id}/import_parsers/{id}": { "get": { "description": "Retrieve a single import parser, including its full `template_json` configuration.", "operationId": "getImportParser", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the import parser", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/import_parser" } } }, "description": "The import parser" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Import parser not found, or vault is unauthorized" } }, "summary": "Get an import parser", "tags": [ "Import Parsers" ] } }, "/vaults/{vault_id}/inventory_locations": { "get": { "description": "Returns a list of inventory locations within the specified vault.", "operationId": "getInventoryLocations", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Authentication token", "in": "header", "name": "X-CDD-Token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/inventory_location" }, "type": "array" } } }, "description": "A list of inventory locations" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Retrieve a list of Sample Inventory Locations for a given Vault", "tags": [ "Inventory" ] } }, "/vaults/{vault_id}/inventory_samples": { "get": { "description": "List inventory samples in the vault. Supports pagination (`page_size`, `offset`), asynchronous retrieval (async=true), and filtering by batch, project, and creation/modification dates. Requires inventory fields to be enabled for the vault.", "operationId": "getInventorySamples", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "If true, run the listing as an asynchronous export.", "in": "query", "name": "async", "schema": { "type": "boolean" } }, { "description": "Comma-separated batch ids to filter by.", "in": "query", "name": "batch_ids", "schema": { "type": "string" } }, { "description": "Comma-separated inventory sample ids to filter by.", "in": "query", "name": "inventory_sample_ids", "schema": { "type": "string" } }, { "description": "Comma-separated project ids to filter by.", "in": "query", "name": "projects", "schema": { "type": "string" } }, { "description": "Only include samples created on or after this time.", "in": "query", "name": "created_after", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include samples created on or before this time.", "in": "query", "name": "created_before", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include samples modified on or after this time.", "in": "query", "name": "modified_after", "schema": { "format": "date-time", "type": "string" } }, { "description": "Only include samples modified on or before this time.", "in": "query", "name": "modified_before", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "objects": { "items": { "$ref": "#/components/schemas/inventory_sample_object" }, "type": "array" }, "offset": { "type": "integer" }, "page_size": { "type": "integer" } }, "required": [ "count", "objects" ], "type": "object" } } }, "description": "A page of inventory samples" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get inventory samples", "tags": [ "Inventory Samples" ] }, "post": { "description": "Create an inventory sample for a batch.", "operationId": "createInventorySample", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_sample_create" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_sample_object" } } }, "description": "The created inventory sample" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Create an inventory sample", "tags": [ "Inventory Samples" ] } }, "/vaults/{vault_id}/inventory_samples/{id}": { "delete": { "description": "Delete an inventory sample. Samples that are associated with a protocol (readout rows) or a plate well cannot be deleted.", "operationId": "deleteInventorySample", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the inventory sample", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } }, "description": "The inventory sample was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The sample cannot be deleted (associated with a protocol or plate well)" } }, "summary": "Delete an inventory sample", "tags": [ "Inventory Samples" ] }, "get": { "description": "Retrieve a single inventory sample.", "operationId": "getInventorySample", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the inventory sample", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_sample_object" } } }, "description": "The inventory sample" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Inventory sample not found, or vault is unauthorized" } }, "summary": "Get an inventory sample", "tags": [ "Inventory Samples" ] }, "put": { "description": "Update an inventory sample. Only the supplied fields are changed. At most one inventory event may be added or updated per request.", "operationId": "updateInventorySample", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the inventory sample", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_sample_update" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inventory_sample_object" } } }, "description": "The updated inventory sample" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update an inventory sample", "tags": [ "Inventory Samples" ] } }, "/vaults/{vault_id}/mapping_templates": { "get": { "description": "This will give you a summary of all the mapping templates.\n\nIf you need details, you need to use the `GET /vaults/{vault_id}/mapping_templates/{mapping_template_id}` endpoint.\n", "operationId": "getMappingTemplates", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/mapping_template_simple" }, "type": "array" } } }, "description": "List of all fields" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Retrieve all the mapping templates", "tags": [ "Mapping Templates" ] } }, "/vaults/{vault_id}/mapping_templates/{mapping_template_id}": { "get": { "description": "This will give you the details about this mapping template\n", "operationId": "getMappingTemplate", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "mapping_template_id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mapping_template_details" } } }, "description": "List of all fields" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Retrieve a single mapping template", "tags": [ "Mapping Templates" ] } }, "/vaults/{vault_id}/molecules": { "post": { "description": "Create a molecule. This is only permitted in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead. To read or search molecules, use `POST /molecules/query`.", "operationId": "createMolecule", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/molecule_create" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/molecule" } } }, "description": "The created molecule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error, or molecule creation is not allowed in this vault" } }, "summary": "Create a molecule", "tags": [ "Molecules" ] } }, "/vaults/{vault_id}/molecules/query": { "post": { "description": "Get the information from multiple molecules. We still support the now deprecated GET queries on the endpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.", "operationId": "getMolecules", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/molecule_query" }, { "$ref": "#/components/schemas/molecule_query_only_id" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/molecule" }, "type": "array" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get multiple molecules", "tags": [ "Molecules" ] } }, "/vaults/{vault_id}/molecules/{id}": { "get": { "description": "Retrieve a single molecule by id. For querying multiple molecules or searching by structure, use `POST /molecules/query`.", "operationId": "getMolecule", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the molecule", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Exclude structure representations (smiles, inchi, molfile, etc.).", "in": "query", "name": "no_structures", "schema": { "type": "boolean" } }, { "description": "Return only the molecule's batch ids instead of full batch objects.", "in": "query", "name": "only_batch_ids", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/molecule" } } }, "description": "The molecule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Molecule not found, or vault is unauthorized" } }, "summary": "Get a molecule", "tags": [ "Molecules" ] }, "put": { "description": "Update a molecule. Only the supplied fields are changed; array fields (synonyms, projects, collections) replace the existing values.", "operationId": "updateMolecule", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the molecule", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/molecule_update" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/molecule" } } }, "description": "The updated molecule" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Molecule not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update a molecule", "tags": [ "Molecules" ] } }, "/vaults/{vault_id}/molecules/{id}/image": { "get": { "description": "Request a rendered image of a molecule's structure. Image generation is asynchronous: this returns an export object whose progress you poll with `GET /export_progress/{export_id}`, then download the image with `GET /exports/{export_id}` once it is finished.", "operationId": "getMoleculeImage", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the molecule", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Image width in pixels.", "in": "query", "name": "width", "schema": { "type": "integer" } }, { "description": "Image height in pixels.", "in": "query", "name": "height", "schema": { "type": "integer" } }, { "description": "Image format.", "in": "query", "name": "format", "schema": { "default": "svg", "enum": [ "svg", "png" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export" } } }, "description": "The export to poll for the generated image" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Molecule not found, or vault is unauthorized" } }, "summary": "Get a molecule image", "tags": [ "Molecules" ] } }, "/vaults/{vault_id}/plates": { "get": { "description": "List plates in the vault. Supports pagination (`page_size`, `offset`), asynchronous retrieval (`async=true`), `only_ids`, and filtering by name, location, project, and creation/modification dates.", "operationId": "getPlates", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "If true, run the listing as an asynchronous export.", "in": "query", "name": "async", "schema": { "type": "boolean" } }, { "description": "If true, return only the ids of matching plates.", "in": "query", "name": "only_ids", "schema": { "type": "boolean" } }, { "description": "Comma-separated plate ids to filter by.", "in": "query", "name": "plates", "schema": { "type": "string" } }, { "description": "Comma-separated plate names to filter by.", "in": "query", "name": "names", "schema": { "type": "string" } }, { "description": "Comma-separated project ids to filter by.", "in": "query", "name": "projects", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/plate_object" }, "type": "array" } } }, "description": "List of plates" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get plates", "tags": [ "Plates" ] }, "post": { "description": "Create a plate. Requires write permission in the vault.", "operationId": "createPlate", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plate_create_update" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plate_object" } } }, "description": "The created plate" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Create a plate", "tags": [ "Plates" ] } }, "/vaults/{vault_id}/plates/{id}": { "delete": { "description": "Delete a plate. Requires write permission. A plate that has associated run data cannot be deleted.", "operationId": "deletePlate", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the plate", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The plate was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Plate not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The plate cannot be deleted (it has associated run data)" } }, "summary": "Delete a plate", "tags": [ "Plates" ] }, "get": { "description": "Retrieve a single plate.", "operationId": "getPlate", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the plate", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plate_object" } } }, "description": "The plate" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Plate not found, or vault is unauthorized" } }, "summary": "Get a plate", "tags": [ "Plates" ] }, "put": { "description": "Update a plate. Requires write permission.", "operationId": "updatePlate", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the plate", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plate_create_update" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plate_object" } } }, "description": "The updated plate" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Plate not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update a plate", "tags": [ "Plates" ] } }, "/vaults/{vault_id}/projects": { "get": { "description": "List the projects accessible to the API key in the vault. Each entry contains the project `id` and `name`.", "operationId": "getProjects", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/project_object" }, "type": "array" } } }, "description": "List of projects" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get projects", "tags": [ "Projects" ] }, "post": { "description": "Create a project. Requires permission to manage projects in the vault. The response contains the new project's `id` and `name`.", "operationId": "createProject", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project_create_update_public" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project_object" } } }, "description": "The created project" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Create a project", "tags": [ "Projects" ] } }, "/vaults/{vault_id}/projects/{id}": { "delete": { "description": "Delete a project. Requires permission to manage projects. A project that still has associated data (runs, models, etc.) may not be deletable.", "operationId": "deleteProject", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the project", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The project was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Project not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "The project cannot be deleted (it still has associated data)" } }, "summary": "Delete a project", "tags": [ "Projects" ] }, "get": { "description": "Retrieve a single project, including its `description` and `members`.", "operationId": "getProject", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the project", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project_object" } } }, "description": "The project" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Project not found, or vault is unauthorized" } }, "summary": "Get a project", "tags": [ "Projects" ] }, "put": { "description": "Update a project. Requires permission to manage projects. Supplying `members` replaces the existing membership list.", "operationId": "updateProject", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the project", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project_create_update_public" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project_object" } } }, "description": "The updated project" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Project not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update a project", "tags": [ "Projects" ] } }, "/vaults/{vault_id}/protocols": { "get": { "description": "List protocols in the vault. Supports pagination (`page_size`, `offset`), asynchronous retrieval (`async=true`), `only_ids`, `no_runs` (omit run data), and filtering by name, project, molecule, plate, and dates.", "operationId": "getProtocols", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "If true, run the listing as an asynchronous export.", "in": "query", "name": "async", "schema": { "type": "boolean" } }, { "description": "If true, return only the ids of matching protocols.", "in": "query", "name": "only_ids", "schema": { "type": "boolean" } }, { "description": "If true, omit run data from each protocol.", "in": "query", "name": "no_runs", "schema": { "type": "boolean" } }, { "description": "Comma-separated protocol names to filter by.", "in": "query", "name": "names", "schema": { "type": "string" } }, { "description": "Comma-separated protocol ids to filter by.", "in": "query", "name": "protocols", "schema": { "type": "string" } }, { "description": "Comma-separated project ids to filter by.", "in": "query", "name": "projects", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "objects": { "items": { "$ref": "#/components/schemas/protocol_object" }, "type": "array" }, "offset": { "type": "integer" }, "page_size": { "type": "integer" } }, "required": [ "count", "objects" ], "type": "object" } } }, "description": "A page of protocols" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get protocols", "tags": [ "Protocols" ] } }, "/vaults/{vault_id}/protocols/{id}": { "get": { "description": "Retrieve a single protocol. Pass `no_runs=true` to omit run data.", "operationId": "getProtocol", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the protocol", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "If true, omit run data from the response.", "in": "query", "name": "no_runs", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/protocol_object" } } }, "description": "The protocol" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol not found, or vault is unauthorized" } }, "summary": "Get a protocol", "tags": [ "Protocols" ] }, "put": { "description": "Update a protocol's definition (name, projects, and protocol field values). This does not modify readout definitions. Requires write permission.", "operationId": "updateProtocol", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the protocol", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/protocol_update" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/protocol_object" } } }, "description": "The updated protocol" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update a protocol", "tags": [ "Protocols" ] } }, "/vaults/{vault_id}/protocols/{protocol_id}/data": { "get": { "description": "Retrieve the readout data (detail rows, with any matching aggregate-row readouts merged in) for a protocol. Supports pagination and filtering by molecule, plate, run, and project. Pass `format=csv` to produce a CSV export instead of JSON.", "operationId": "getProtocolData", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the protocol", "in": "path", "name": "protocol_id", "required": true, "schema": { "type": "integer" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "If true, run the query as an asynchronous export.", "in": "query", "name": "async", "schema": { "type": "boolean" } }, { "description": "If \"csv\", produce a CSV export instead of a JSON page.", "in": "query", "name": "format", "schema": { "type": "string" } }, { "description": "Comma-separated molecule ids to filter by.", "in": "query", "name": "molecules", "schema": { "type": "string" } }, { "description": "Comma-separated run ids to filter by.", "in": "query", "name": "runs", "schema": { "type": "string" } }, { "description": "Comma-separated plate ids to filter by.", "in": "query", "name": "plates", "schema": { "type": "string" } }, { "description": "Comma-separated project ids to filter by.", "in": "query", "name": "projects", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "objects": { "items": { "properties": { "batch": { "type": "integer" }, "id": { "type": "integer" }, "molecule": { "type": "integer" }, "readouts": { "additionalProperties": true, "description": "Readout values keyed by readout definition id.", "type": "object" }, "run": { "type": "integer" }, "well": { "additionalProperties": true, "type": "object" } }, "type": "object" }, "type": "array" }, "offset": { "type": "integer" }, "page_size": { "type": "integer" } }, "required": [ "count", "objects" ], "type": "object" } } }, "description": "A page of protocol readout data" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get protocol data", "tags": [ "Protocols" ] } }, "/vaults/{vault_id}/batches/{batch_id}/protocols/{id}/plot": { "get": { "description": "Generate dose-response plot image(s) for a batch within a protocol. By default, returns a ZIP archive containing one PNG per dose-response calculation on the protocol. Pass `dose_response_calculation_id` to get a single PNG for one calculation instead.", "operationId": "getDoseResponsePlot", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the batch", "in": "path", "name": "batch_id", "required": true, "schema": { "type": "integer" } }, { "description": "Numeric identifier of the protocol", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Restrict the plot to a single dose-response calculation. When provided, a single PNG is returned; when omitted, a ZIP of PNGs is returned.", "in": "query", "name": "dose_response_calculation_id", "schema": { "type": "integer" } }, { "description": "Image size multiplier.", "in": "query", "name": "size", "schema": { "enum": [ "small", "medium", "large" ], "type": "string" } }, { "description": "Comma-separated run ids to restrict the plotted data to.", "in": "query", "name": "runs", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/png": { "schema": { "format": "binary", "type": "string" } }, "application/zip": { "schema": { "format": "binary", "type": "string" } } }, "description": "A single PNG (when `dose_response_calculation_id` is given) or a ZIP archive of PNGs (otherwise)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "No data found for this batch/protocol, or vault is unauthorized" } }, "summary": "Get dose-response plot", "tags": [ "Protocols" ] } }, "/vaults/{vault_id}/readout_rows/query": { "post": { "description": "Get multiple readout rows (rows of protocol data). We still support the now deprecated GET queries on the endpoint without 'query' in it and passing query parameters in the URL. It is highly recommended that you switch your applications to the POST queries described here.\n\nWhen async is true the request returns an export to poll instead of the readout rows; check it with the GET export progress call and retrieve the result with the GET export call.", "operationId": "getReadoutRows", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/readout_row_query" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "description": "Synchronous response", "properties": { "count": { "description": "Total number of readout rows matching the query", "type": "integer" }, "objects": { "items": { "$ref": "#/components/schemas/readout_row" }, "type": "array" }, "offset": { "type": "integer" }, "page_size": { "type": "integer" } }, "type": "object" }, { "$ref": "#/components/schemas/export" } ] } } }, "description": "The matching readout rows, or the export to poll when async is true" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Invalid query parameters, such as an illegal type" } }, "summary": "Get multiple readout rows", "tags": [ "Readout Rows" ] } }, "/vaults/{vault_id}/readout_rows/{readout_row_id}": { "delete": { "description": "Delete a single readout row (row of protocol data). Only detail rows can be deleted; aggregate rows cannot be deleted via the API.\n", "operationId": "deleteReadoutRow", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "readout_row_id", "required": true, "schema": { "description": "Numeric identifier of the readout row", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "example": "Readout row with ID 1 has been destroyed", "type": "string" } }, "type": "object" } } }, "description": "The readout row was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Aggregate rows can't be destroyed via the API. Only detail rows can be destroyed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Couldn't find this readout row" } }, "summary": "Delete a readout row", "tags": [ "Readout Rows" ] }, "put": { "description": "Updates an existing readout row (including the ability to flag an existing readout row as an outlier).\n\nThis PUT Readout_Rows API call allows users to update a specified row of Protocol data or flag a specified row of Protocol data as an outlier. Only detail rows can be updated; aggregate rows cannot be updated via the API.\n\nNoteworthy tips:\n- The GET Protocol Data API call will be useful to ascertain the id of the readout row for the Protocol data you wish to edit. - The GET Protocols API call also provides the readout definition IDs.\n", "operationId": "updateReadoutRow", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "readout_row_id", "required": true, "schema": { "description": "Numeric identifier of the readout row", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "readouts": { "additionalProperties": { "properties": { "outlier": { "description": "Flag (or unflag) this readout as an outlier", "type": "boolean" }, "value": { "description": "New value for this readout" } }, "type": "object" }, "description": "New readout values and/or outlier flags, keyed by readout definition ID", "example": { "283130": { "value": 99 }, "283131": { "outlier": true } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "example": 1, "type": "integer" }, "readouts": { "additionalProperties": true, "description": "Readout values keyed by readout definition ID", "type": "object" } }, "type": "object" } } }, "description": "The updated readout row" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Invalid readout keys (only \"value\" and \"outlier\" are allowed), invalid outlier flag value, or the readout cannot be flagged as an outlier" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Aggregate rows can't be updated via the API. Only detail rows can be updated" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Couldn't find this readout row or one of its readouts" } }, "summary": "Update existing row", "tags": [ "Readout Rows" ] } }, "/vaults/{vault_id}/registration_forms": { "get": { "description": "List the registration forms configured in the vault.", "operationId": "getRegistrationForms", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/registration_form" }, "type": "array" } } }, "description": "List of registration forms" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get registration forms", "tags": [ "Registration Forms" ] } }, "/vaults/{vault_id}/registration_forms/{id}": { "get": { "description": "Retrieve a single registration form.", "operationId": "getRegistrationForm", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the registration form", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/registration_form" } } }, "description": "The registration form" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Registration form not found, or vault is unauthorized" } }, "summary": "Get a registration form", "tags": [ "Registration Forms" ] } }, "/vaults/{vault_id}/registration_systems": { "get": { "description": "List the registration systems defined in the vault.", "operationId": "getRegistrationSystems", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/public_registration_system" }, "type": "array" } } }, "description": "List of registration systems" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get registration systems", "tags": [ "Registration Systems" ] } }, "/vaults/{vault_id}/registration_systems/{id}": { "get": { "description": "Retrieve a single registration system.", "operationId": "getRegistrationSystem", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the registration system", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/public_registration_system" } } }, "description": "The registration system" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Registration system not found, or vault is unauthorized" } }, "summary": "Get a registration system", "tags": [ "Registration Systems" ] } }, "/vaults/{vault_id}/runs": { "delete": { "description": "Delete all runs that were imported by a given slurp. Pass the slurp id as the `slurp` query parameter. Requires write permission for all affected runs. (To delete a single run, use `DELETE /runs/{id}`.)", "operationId": "deleteRunsBySlurp", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Id of the slurp whose runs should be deleted.", "in": "query", "name": "slurp", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "status": { "type": "integer" } }, "type": "object" } } }, "description": "The slurp's runs were deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Delete runs by slurp", "tags": [ "Runs" ] }, "get": { "description": "List runs in the vault. Supports pagination (`page_size`, `offset`), asynchronous retrieval (`async=true`), `only_ids`, and filtering by protocol, project, slurp, run date, and creation/modification dates.", "operationId": "getRuns", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Maximum number of records to return (default 50, maximum 1000).", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Number of records to skip (for pagination).", "in": "query", "name": "offset", "schema": { "type": "integer" } }, { "description": "If true, run the listing as an asynchronous export.", "in": "query", "name": "async", "schema": { "type": "boolean" } }, { "description": "If true, return only the ids of matching runs.", "in": "query", "name": "only_ids", "schema": { "type": "boolean" } }, { "description": "Comma-separated protocol ids to filter by.", "in": "query", "name": "protocols", "schema": { "type": "string" } }, { "description": "Comma-separated project ids to filter by.", "in": "query", "name": "projects", "schema": { "type": "string" } }, { "description": "Only include runs imported by this slurp id.", "in": "query", "name": "slurp", "schema": { "type": "integer" } }, { "description": "Include runs with a run date on/after this date.", "in": "query", "name": "run_date_after", "schema": { "format": "date", "type": "string" } }, { "description": "Include runs with a run date on/before this date.", "in": "query", "name": "run_date_before", "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/run_object" }, "type": "array" } } }, "description": "List of runs" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get runs", "tags": [ "Runs" ] } }, "/vaults/{vault_id}/runs/{id}": { "delete": { "description": "Delete a single run. Requires write permission.", "operationId": "deleteRun", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the run", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The run was deleted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Run not found, or vault is unauthorized" } }, "summary": "Delete a run", "tags": [ "Runs" ] }, "get": { "description": "Retrieve a single run, including its plate statistics.", "operationId": "getRun", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the run", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/run_object" } } }, "description": "The run" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Run not found, or vault is unauthorized" } }, "summary": "Get a run", "tags": [ "Runs" ] }, "put": { "description": "Update a run. Only the supplied fields are changed. Use `project_id` to move the run to a different project. Requires write permission.", "operationId": "updateRun", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the run", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/run_update" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/run_object" } } }, "description": "The updated run" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Run not found, or vault is unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error" } }, "summary": "Update a run", "tags": [ "Runs" ] } }, "/vaults/{vault_id}/searches": { "get": { "description": "Return a list of accessible saved searches for the given vault.", "operationId": "all_saved_searches", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/saved_search_session" }, "type": "array" } } }, "description": "List of saved searches, each including its full `search_criteria` (structure, keyword, and molecule/collection/protocol criteria) and `display_criteria`." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "List of all saved searches", "tags": [ "Searches" ] } }, "/vaults/{vault_id}/searches/{search_id}": { "get": { "description": "Unlike other calls, saved searches can only be performed asynchronously.\n\nReturns an export id and status.\n\nSee Async Exports for how to check on the status of your call and retrieving the data once it has finished.\n", "operationId": "execute_search", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "search_id", "required": true, "schema": { "type": "integer" } }, { "description": "Comma separated list of the ids of the projects to search", "explode": false, "in": "query", "name": "projects", "required": false, "schema": { "items": { "type": "integer" }, "type": "array" }, "style": "form" }, { "description": "Comma separated list of the ids of the data sets to search", "explode": false, "in": "query", "name": "data_sets", "required": false, "schema": { "items": { "type": "integer" }, "type": "array" }, "style": "form" }, { "description": "Should it be zipped", "in": "query", "name": "zip", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Format of the exported file", "in": "query", "name": "format", "required": false, "schema": { "default": "csv", "enum": [ "csv", "sdf", "xls", "xlsx" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/export" } } }, "description": "Export information" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Execute a given search", "tags": [ "Searches" ] } }, "/vaults/{vault_id}/slurps": { "get": { "description": "List the active slurps (data import jobs) in the vault. Pass `show_events=true` to include the ambiguous/suspicious events and import errors raised during import.", "operationId": "getSlurps", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Include event and error details for each slurp.", "in": "query", "name": "show_events", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/slurp" }, "type": "array" } } }, "description": "List of active slurps" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get slurps", "tags": [ "Slurps" ] }, "post": { "description": "Start a new slurp (data import) by uploading a file. The request must be sent as `multipart/form-data`: the data file is the `file` part, and any import metadata is supplied as a JSON string in the `json` part. The new slurp is created in the `mapping` state; poll the slurp to follow its progress.", "operationId": "createSlurp", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "The data file to import (CSV, XLSX, SDF, etc.).", "format": "binary", "type": "string" }, "json": { "description": "Import metadata (such as mapping options) encoded as a JSON string.", "type": "string" } }, "required": [ "file" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/slurp" } } }, "description": "The created slurp" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Too many concurrent slurps for this user" } }, "summary": "Create a slurp", "tags": [ "Slurps" ] } }, "/vaults/{vault_id}/slurps/{id}": { "get": { "description": "Retrieve a single slurp. Pass `show_events=true` to include the ambiguous/suspicious events and import errors raised during import.", "operationId": "getSlurp", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "Numeric identifier of the slurp", "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Include event and error details.", "in": "query", "name": "show_events", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/slurp" } } }, "description": "The slurp" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Slurp not found, or vault is unauthorized" } }, "summary": "Get a slurp", "tags": [ "Slurps" ] } }, "/vaults/{vault_id}/status": { "get": { "description": "Retrieve the operational status of the vault: currently running imports (slurps), recalculating protocols, and overall availability of the background processing services. Requires vault administrator access.", "operationId": "getVaultStatus", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vault_status" } } }, "description": "The current vault status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "Get vault status", "tags": [ "Status" ] } }, "/vaults/{vault_id}/users": { "get": { "description": "Returns a list of CDD Vault members.\n\nNoteworthy Tips:\n- Only Vault Administrators can use this GET Users API call.\n- This API call is useful to identify the Members' IDs of users for use in the GET ELN Entries API call.\n", "operationId": "get_vault_users", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "description": "If true, each user’s Vault role and an array of project memberships are returned", "in": "query", "name": "include_projects", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Default": { "value": [ { "first_name": "Ada", "id": 1234, "last_name": "Lovelace" }, { "first_name": "Ada", "id": 9876, "last_name": "Ecalevol" } ] }, "IncludeProjects": { "value": [ { "first_name": "Ada", "id": 1234, "last_name": "Lovelace", "projects": [ { "can_edit_data": true, "can_manage_project": true, "hidden": false, "id": 4444, "name": "Corporate data" } ] } ] } }, "schema": { "anyOf": [ { "items": { "properties": { "first_name": { "type": "string" }, "id": { "type": "integer" }, "last_name": { "type": "string" } }, "type": "object" }, "type": "array" }, { "items": { "properties": { "first_name": { "type": "string" }, "id": { "type": "integer" }, "last_name": { "type": "string" }, "projects": { "items": { "properties": { "can_edit_data": { "type": "boolean" }, "can_manage_project": { "type": "boolean" }, "hidden": { "type": "boolean" }, "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } ] } } }, "description": "Users of the vault" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" } }, "summary": "List of users of a vault", "tags": [ "Users" ] } }, "/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations": { "get": { "description": "Get all dose response calculations for a protocol.\n", "operationId": "getDoseResponseCalculations", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "protocol_id", "required": true, "schema": { "$ref": "#/components/schemas/protocol_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calculations_list" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol not found" } }, "summary": "List dose response calculations for a protocol", "tags": [ "Dose Response Calculations" ] } }, "/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}": { "get": { "description": "Get the details of a single dose response calculation", "operationId": "getDoseResponseCalculation", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "protocol_id", "required": true, "schema": { "$ref": "#/components/schemas/protocol_id" } }, { "in": "path", "name": "dose_response_calculation_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_calculation_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calculation" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol or dose response calculation not found" } }, "summary": "Get a single dose response calculation", "tags": [ "Dose Response Calculations" ] }, "put": { "description": "Update a dose response calculation's fit parameters and/or minimum activity bounds.\n\nTo set a fixed constraint, use modifier \"=\" with a value.\nTo set a range constraint, use modifier \"from\" with a range object containing min and max.\nTo set a comparison constraint, use modifier \">\", \">=\", \"<\", or \"<=\" with a value.\nTo clear all fit parameter constraints, pass an empty fit_parameters object.\n", "operationId": "updateDoseResponseCalculation", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "protocol_id", "required": true, "schema": { "$ref": "#/components/schemas/protocol_id" } }, { "in": "path", "name": "dose_response_calculation_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_calculation_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calculation_update" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/calculation" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key or insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol or dose response calculation not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error. Possible causes include: unknown fit parameter, invalid modifier, range where lower > upper, non-numeric value, or unrecognized parameters.\n" } }, "summary": "Update a dose response calculation", "tags": [ "Dose Response Calculations" ] } }, "/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series": { "get": { "description": "Get all dose response data series for a dose response calculation. Each data series represents the curve data for a specific batch/run combination.\n", "operationId": "getDoseResponseDataSeriesList", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "protocol_id", "required": true, "schema": { "$ref": "#/components/schemas/protocol_id" } }, { "in": "path", "name": "dose_response_calculation_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_calculation_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dose_response_data_series_list" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol or dose response calculation not found" } }, "summary": "List dose response data series for a dose response calculation", "tags": [ "Dose Response Data Series" ] } }, "/vaults/{vault_id}/protocols/{protocol_id}/dose_response_calculations/{dose_response_calculation_id}/dose_response_data_series/{dose_response_data_series_id}": { "get": { "description": "Get the details of a single dose response data series", "operationId": "getDoseResponseDataSeries", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "protocol_id", "required": true, "schema": { "$ref": "#/components/schemas/protocol_id" } }, { "in": "path", "name": "dose_response_calculation_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_calculation_id" } }, { "in": "path", "name": "dose_response_data_series_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_data_series_id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dose_response_data_series" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol, dose response calculation, or dose response data series not found" } }, "summary": "Get a single dose response data series", "tags": [ "Dose Response Data Series" ] }, "put": { "description": "Update a dose response data series's fit parameters. These constraints override the calculation-level constraints for this specific curve.\n\nTo set a fixed constraint, use modifier \"=\" with a value.\nTo set a range constraint, use modifier \"from\" with a range object containing min and max.\nTo set a comparison constraint, use modifier \">\", \">=\", \"<\", or \"<=\" with a value.\nTo set unconstrained (best fit), use modifier \"best fit\" (data series only).\n", "operationId": "updateDoseResponseDataSeries", "parameters": [ { "in": "path", "name": "vault_id", "required": true, "schema": { "$ref": "#/components/schemas/vault_id" } }, { "in": "path", "name": "protocol_id", "required": true, "schema": { "$ref": "#/components/schemas/protocol_id" } }, { "in": "path", "name": "dose_response_calculation_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_calculation_id" } }, { "in": "path", "name": "dose_response_data_series_id", "required": true, "schema": { "$ref": "#/components/schemas/dose_response_data_series_id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dose_response_data_series_update" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dose_response_data_series" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_apikey" } } }, "description": "Missing or invalid API key or insufficient permissions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Protocol, dose response calculation, or dose response data series not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } }, "description": "Validation error. Possible causes include: unknown fit parameter, invalid modifier, range where lower > upper, or non-numeric value.\n" } }, "summary": "Update a dose response data series", "tags": [ "Dose Response Data Series" ] } }, "/vaults/{vault_id}/ai/bioisosteres": { "post": { "summary": "Find bioisosteric replacements (hierarchical)", "tags": [ "Deep Learning Bioisosteres" ], "operationId": "ai_bioisosteres", "description": "Submit a chemical structure and receive bioisosteric replacement suggestions grouped by fragment. Requires the vault to have Deep Learning enabled.", "security": [], "parameters": [ { "name": "vault_id", "in": "path", "required": true, "description": "ID of the current vault.", "schema": { "type": "integer" } }, { "name": "X-CDD-Token", "in": "header", "required": true, "description": "API key token for authentication.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns bioisosteric suggestions grouped by fragment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "string", "example": "OK" }, "mocked_service": { "type": "boolean", "description": "true only on the dev mock, not the real service" }, "result": { "type": "object", "required": [ "query", "suggestions" ], "properties": { "query": { "type": "string", "example": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1" }, "suggestions": { "type": "array", "items": { "type": "object", "required": [ "fragment", "size", "atom_indices", "bioisosteres" ], "properties": { "fragment": { "type": "string", "example": "[16*]c1ccc(Cl)cc1Cl" }, "size": { "type": "integer", "example": 8 }, "atom_indices": { "type": "array", "items": { "type": "integer" }, "example": [ 0, 1 ] }, "bioisosteres": { "type": "array", "items": { "type": "object", "required": [ "fragment", "structure", "synthetic_feasibility", "tanimoto", "atom_indices" ], "properties": { "fragment": { "type": "string", "example": "[16*]c1ccc(F)cc1Cl" }, "inchikey": { "type": "string", "example": "QCNPSEBNVBYHLY-UHFFFAOYSA-N" }, "structure": { "type": "string", "example": "c1ccncc1" }, "tanimoto": { "type": "number", "format": "float", "example": 0.875 }, "atom_indices": { "type": "array", "items": { "type": "integer" }, "example": [ 0, 1 ] }, "synthetic_feasibility": { "type": "object", "required": [ "synthetic_feasibility_score", "profile_overlap", "bits_missing", "fraction_missing" ], "properties": { "synthetic_feasibility_score": { "type": "number", "format": "float", "example": 0.9 }, "profile_overlap": { "type": "number", "format": "float", "example": 0.8 }, "bits_missing": { "type": "number", "format": "float", "example": 0.1 }, "fraction_missing": { "type": "number", "format": "float", "example": 0.2 } } }, "alerts": { "type": "array", "items": { "type": "object", "required": [ "filter_set", "description" ], "properties": { "filter_set": { "type": "string", "example": "Brenk" }, "description": { "type": "string", "example": "aniline" } } } }, "identifiers": { "type": "array", "items": { "type": "object", "required": [ "name", "collection" ], "properties": { "name": { "type": "string", "example": "SCHEMBL11832241" }, "collection": { "type": "string", "example": "SureChEMBL" }, "patent": { "type": "object", "required": [ "count", "first_patent", "first_date" ], "properties": { "count": { "type": "integer", "example": 1 }, "first_date": { "type": "string", "format": "date", "example": "1976-01-20" }, "first_patent": { "type": "string", "example": "US-3933824-A" } } }, "cdd_public": { "type": "object", "required": [ "molecule_id" ], "properties": { "molecule_id": { "type": "integer", "example": 123456 } } }, "cdd_private": { "type": "object", "required": [ "id", "standard_inchi_key", "exact" ], "properties": { "id": { "type": "integer", "example": 123456 }, "standard_inchi_key": { "type": "string", "example": "QCNPSEBNVBYHLY-UHFFFAOYSA-N" }, "exact": { "type": "boolean", "example": true } } } } } } } } } } } } } } } } } } }, "400": { "description": "Bad request — missing or invalid parameters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "structure parameter is required" }, "code": { "type": "integer", "example": 400 } } } } } }, "401": { "description": "Unauthorized — Deep Learning not enabled for this vault or user lacks access.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "Dl bioisosteres endpoint only accessible in vaults with Deep Learning enabled" }, "code": { "type": "integer", "example": 401 } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "structure" ], "properties": { "structure": { "type": "string", "description": "SMILES or MOL representation of structure to find bioisosteric replacements for.", "example": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1" }, "number_suggestions": { "type": "integer", "description": "Number of bioisosteric suggestions per fragment. Defaults to 5, max 200.", "example": 5 }, "return_known_identifiers": { "type": "boolean", "description": "Include known identifiers (InChIKey, etc.) in response. Defaults to false.", "example": false }, "lookup_internal_identifiers": { "type": "boolean", "description": "Opt in to server-side enrichment with internal vault identifiers. When true, each bioisostere's InChIKey is used to find molecules in the Vault. The 14-character prefix of the InChIKey is used to catch stereochemical variants. The internal identifiers are appended to the identifiers array as an `Internal` collection. Defaults to false.", "example": false }, "filter_structure_alerts": { "type": "boolean", "description": "Filter out suggestions with additional structural alerts. Defaults to true.", "example": true }, "filter_by_atom_indices": { "type": "array", "items": { "type": "integer" }, "description": "List of atom indices identifying which fragments to include in fragmentation. Each suggestion fragment whose `atom_indices` overlaps this list is kept. If omitted, all fragments are used.", "example": [ 0, 1 ] } } } } }, "required": true } } }, "/vaults/{vault_id}/ai/bioisosteres/flat": { "post": { "summary": "Find bioisosteric replacements (flat list)", "tags": [ "Deep Learning Bioisosteres" ], "operationId": "ai_bioisosteres_flat", "description": "Submit a chemical structure and receive bioisosteric replacement suggestions as a flat list. Requires the vault to have Deep Learning enabled.", "security": [], "parameters": [ { "name": "vault_id", "in": "path", "required": true, "description": "ID of the current vault.", "schema": { "type": "integer" } }, { "name": "X-CDD-Token", "in": "header", "required": true, "description": "API key token for authentication.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns bioisosteric suggestions as a flat list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "suggestions" ], "properties": { "query": { "type": "string", "example": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1" }, "suggestions": { "type": "array", "items": { "type": "object", "required": [ "structure", "fragment", "replacement_fragment", "tanimoto", "alerts" ], "properties": { "structure": { "type": "string", "example": "Fc1ccc(-c2n[nH]c3c2CCNCC3)cc1F" }, "fragment": { "type": "string", "example": "[16*]c1ccc(Cl)cc1Cl" }, "replacement_fragment": { "type": "string", "example": "[16*]c1ccc(F)cc1F" }, "tanimoto": { "type": "number", "format": "float", "example": 0.875 }, "synthetic_feasibility_score": { "type": "number", "format": "float", "example": 0.9 }, "identifiers": { "type": "string", "example": "SCHEMBL11832241, CHEMBL12345678" }, "alerts": { "type": "string", "example": "acid_halide,carbonyl_halide" } } } } } } } } }, "400": { "description": "Bad request — missing or invalid parameters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "structure parameter is required" }, "code": { "type": "integer", "example": 400 } } } } } }, "401": { "description": "Unauthorized — Deep Learning not enabled for this vault or user lacks access.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "Dl bioisosteres endpoint only accessible in vaults with Deep Learning enabled" }, "code": { "type": "integer", "example": 401 } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "structure" ], "properties": { "structure": { "type": "string", "description": "SMILES or MOL representation of structure to find bioisosteric replacements for.", "example": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1" }, "number_suggestions": { "type": "integer", "description": "Number of bioisosteric suggestions per fragment. Defaults to 5, max 200.", "example": 5 }, "return_known_identifiers": { "type": "boolean", "description": "Include known identifiers (InChIKey, etc.) in response. Defaults to false.", "example": false }, "lookup_internal_identifiers": { "type": "boolean", "description": "Opt in to server-side enrichment with internal vault identifiers. When true, each bioisostere's InChIKey is used to find molecules in the Vault. The 14-character prefix of the InChIKey is used to catch stereochemical variants. The internal identifiers are appended to the identifiers array as an `Internal` collection. Defaults to false.", "example": false }, "filter_structure_alerts": { "type": "boolean", "description": "Filter out suggestions with additional structural alerts. Defaults to true.", "example": true }, "filter_by_atom_indices": { "type": "array", "items": { "type": "integer" }, "description": "List of atom indices identifying which fragments to include in fragmentation. Each suggestion fragment whose `atom_indices` overlaps this list is kept. If omitted, all fragments are used.", "example": [ 0, 1 ] } } } } }, "required": true } } }, "/vaults/{vault_id}/ai/bioisosteres/get_fragmentation": { "post": { "summary": "Fragment a chemical structure", "tags": [ "Deep Learning Bioisosteres" ], "operationId": "ai_bioisosteres_get_fragmentation", "description": "Submit a chemical structure and receive its fragmentation without bioisosteric suggestions. Requires the vault to have Deep Learning enabled.", "security": [], "parameters": [ { "name": "vault_id", "in": "path", "required": true, "description": "ID of the current vault.", "schema": { "type": "integer" } }, { "name": "X-CDD-Token", "in": "header", "required": true, "description": "API key token for authentication.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns the fragmentation of the structure.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "string", "example": "OK" }, "mocked_service": { "type": "boolean", "description": "true only on the dev mock, not the real service" }, "result": { "type": "object", "required": [ "query", "suggestions" ], "properties": { "query": { "type": "string", "example": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1" }, "suggestions": { "type": "array", "items": { "type": "object", "required": [ "fragment", "size", "atom_indices" ], "properties": { "fragment": { "type": "string", "example": "[16*]c1ccc(Cl)cc1Cl" }, "size": { "type": "integer", "example": 8 }, "atom_indices": { "type": "array", "items": { "type": "integer" }, "example": [ 0, 1 ] } } } } } } } } } } }, "400": { "description": "Bad request — missing or invalid parameters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "structure parameter is required" }, "code": { "type": "integer", "example": 400 } } } } } }, "401": { "description": "Unauthorized — Deep Learning not enabled for this vault or user lacks access.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "Dl bioisosteres endpoint only accessible in vaults with Deep Learning enabled" }, "code": { "type": "integer", "example": 401 } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "structure" ], "properties": { "structure": { "type": "string", "description": "SMILES or MOL representation of structure to fragment.", "example": "Clc1ccc(COC(Cn2ccnc2)c2ccc(Cl)cc2Cl)c(Cl)c1" } } } } }, "required": true } } }, "/vaults/{vault_id}/ai/similarity": { "post": { "summary": "Find similar structures using Deep Learning", "tags": [ "Deep Learning Similarity" ], "operationId": "ai_similarity_search", "description": "Submit a chemical structure and receive a ranked list of similar structures using the Deep Learning similarity model. Requires the vault to have Deep Learning enabled.", "security": [], "parameters": [ { "name": "vault_id", "in": "path", "required": true, "description": "ID of the current vault.", "schema": { "type": "integer" } }, { "name": "X-CDD-Token", "in": "header", "required": true, "description": "API key token for authentication.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns similar structures ranked by Tanimoto similarity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "result" ], "properties": { "status": { "type": "string", "example": "OK" }, "mocked_service": { "type": "boolean", "description": "true only on the dev mock, not the real service" }, "result": { "type": "object", "required": [ "query", "query_scaffold", "hits", "metadata" ], "properties": { "query": { "type": "string", "example": "Nc1ccccc1CCCC" }, "query_scaffold": { "type": "string", "example": "c1ccccc1" }, "hits": { "type": "array", "items": { "type": "object", "required": [ "structure", "inchikey", "identifiers", "names", "scaffold", "similarity", "tanimoto", "distance" ], "properties": { "structure": { "type": "string", "example": "Cc1ccncc1" }, "inchikey": { "type": "string", "example": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N" }, "identifiers": { "type": "array", "items": { "type": "object", "required": [ "name", "collection" ], "properties": { "name": { "type": "string", "example": "SCHEMBL11832241" }, "collection": { "type": "string", "example": "SureChEMBL" }, "patent": { "type": "object", "required": [ "count", "first_patent", "first_date" ], "properties": { "count": { "type": "integer", "example": 1 }, "first_date": { "type": "string", "format": "date", "example": "1976-01-20" }, "first_patent": { "type": "string", "example": "US-3933824-A" } } }, "cdd_public": { "type": "object", "required": [ "molecule_id" ], "properties": { "molecule_id": { "type": "integer", "example": 123456 } } }, "cdd_private": { "type": "object", "required": [ "id", "standard_inchi_key", "exact" ], "properties": { "id": { "type": "integer", "example": 123456 }, "standard_inchi_key": { "type": "string", "example": "QCNPSEBNVBYHLY-UHFFFAOYSA-N" }, "exact": { "type": "boolean", "example": true } } } } } }, "names": { "type": "array", "items": { "type": "string" }, "example": [ "Compound A", "CDD-123456" ] }, "scaffold": { "type": "string", "example": "c1ccncc1" }, "similarity": { "type": "number", "format": "float", "example": 0.851 }, "tanimoto": { "type": "number", "format": "float", "example": 0.123 }, "distance": { "type": "number", "format": "float", "example": 10.15 } } } }, "metadata": { "type": "array", "items": { "type": "object", "required": [ "collection", "search_engine", "metric", "count", "release" ], "properties": { "collection": { "type": "string", "example": "CDD Public" }, "search_engine": { "type": "string", "example": "faiss" }, "metric": { "type": "string", "example": "Metric.L2" }, "count": { "type": "integer", "example": 123456 }, "release": { "type": "string", "example": "2024-06" } } } } } } } } } } }, "400": { "description": "Bad request — missing or invalid parameters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "structure parameter is required" }, "code": { "type": "integer", "example": 400 } } } } } }, "401": { "description": "Unauthorized — Deep Learning not enabled for this vault or user lacks access.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "example": "Dl similarity endpoint only accessible in vaults with Deep Learning enabled" }, "code": { "type": "integer", "example": 401 } } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "structure" ], "properties": { "structure": { "type": "string", "description": "SMILES or MOL representation to find similar structures for.", "example": "c1ccccc1" }, "count": { "type": "integer", "description": "Number of similar structures to return. Defaults to 10, max 300.", "example": 10 }, "collections": { "type": "array", "items": { "type": "string" }, "description": "List of collection identifiers to filter results by. If omitted, all collections are included.", "example": [ "SureChEMBL", "ChEMBL" ] }, "return_patents": { "type": "boolean", "description": "Whether to include patent information for compounds in results. Defaults to true.", "example": true }, "lookup_internal_identifiers": { "type": "boolean", "description": "Opt in to server-side enrichment with internal vault identifiers. When true, each hit's InChIKey is used to find molecules in the Vault. The 14-character prefix of the InChIKey is used to catch stereochemical variants. The internal identifiers are appended to the identifiers array as an `Internal` collection. Defaults to false.", "example": false } } } } }, "required": true } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "in": "header", "name": "X-CDD-Token", "type": "apiKey" } }, "schemas": { "error_apikey": { "description": "Whenever the given API key doesn't allow access to the given vault or the vault doesn't exist", "properties": { "code": { "default": 401, "type": "integer" }, "error": { "default": "key not authorized for access to this vault", "type": "string" } }, "type": "object" }, "vault_id": { "description": "Numeric identifier of the vault", "type": "integer" }, "field": { "properties": { "data_type_name": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "overwritable": { "type": "boolean" }, "required_group_number": { "type": "integer" }, "type": { "type": "string" }, "unique_value": { "type": "boolean" } }, "type": "object" }, "fields": { "properties": { "batch": { "items": { "$ref": "#/components/schemas/field" }, "type": "array" }, "internal": { "items": { "$ref": "#/components/schemas/field" }, "type": "array" }, "molecule": { "items": { "$ref": "#/components/schemas/field" }, "type": "array" }, "protocol": { "items": { "$ref": "#/components/schemas/field" }, "type": "array" } }, "type": "object" }, "pick_list_value_object": { "description": "A pick list value belonging to a vault field definition.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "hidden": { "description": "Whether the value is hidden from users.", "type": "boolean" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "value": { "type": "string" } }, "required": [ "id", "value", "hidden", "created_at", "modified_at" ], "type": "object" }, "pick_list_value_write": { "description": "Attributes for creating or updating a pick list value.", "example": { "value": "blue", "hidden": false }, "properties": { "hidden": { "default": false, "description": "Whether the value is hidden from users.", "type": "boolean" }, "value": { "type": "string" } }, "required": [ "value" ], "type": "object" }, "error": { "description": "A general error response containing an error message and HTTP status code", "properties": { "code": { "description": "HTTP status code", "type": "integer", "example": 404 }, "error": { "description": "Human-readable error message", "type": "string", "example": "Resource not found" } }, "type": "object" }, "batch_move_job": { "properties": { "batch": { "description": "The ID of the batch to move", "type": "integer" }, "class": { "description": "The class of the job", "example": "batch move job", "type": "string" }, "created_at": { "description": "The creation time of the batch move job", "format": "date-time", "type": "string" }, "fail_on_molecule_deletion": { "description": "Whether to fail if moving the batch would trigger the removal of the originating molecule", "type": "boolean" }, "id": { "description": "The ID of the batch move job", "type": "integer" }, "modified_at": { "description": "The modification time of the batch move job", "format": "date-time", "type": "string" }, "molecule": { "description": "The ID of the molecule to move the batch to", "type": "integer" }, "name": { "description": "The new name given to the batch. Only present when a name was supplied at creation (allowed only for vaults without a registration system).", "type": "string" }, "queued_job_position": { "description": "Position of the job in the processing queue. Only present while the job is queued.", "type": "integer" }, "requested_by": { "description": "The ID of the user who requested the batch move job", "type": "integer" }, "status": { "description": "The status of the batch move job. A job starts as `requested` and transitions through the queue until it reaches a terminal state (`success`, `failure`, or `canceled`).", "enum": [ "requested", "queued", "processing", "success", "failure", "canceled" ], "example": "requested", "type": "string" }, "status_message": { "description": "Human-readable description of the job's current status.", "type": "string" } }, "required": [ "id", "class", "created_at", "modified_at", "status", "fail_on_molecule_deletion", "molecule", "batch", "requested_by" ], "type": "object" }, "batch_move_job_create": { "description": "Parameters for creating a batch move job, which moves a batch to a different molecule in the same vault.", "example": { "batch": 618771089, "molecule": 1, "fail_on_molecule_deletion": true }, "properties": { "batch": { "description": "The ID of the batch to move.", "type": "integer" }, "fail_on_molecule_deletion": { "default": true, "description": "Fail the job if moving the batch would trigger removal of the originating molecule. Defaults to true.", "type": "boolean" }, "molecule": { "description": "The ID of the molecule to move the batch to.", "type": "integer" }, "name": { "description": "A new name for the batch. Optional, and only allowed for vaults without a registration system.", "type": "string" } }, "required": [ "batch", "molecule" ], "type": "object" }, "batch_create": { "properties": { "batch_fields": { "additionalProperties": { "type": "string" }, "description": "Only in registration vaults\n\nEach vault has its own settings on the minimum information required to create a new Batch (for a Vault Administrator, see Settings > Vault > Batch Fields, to change which Batch fields are required).\n\n{: , ... }\n", "type": "object" }, "molecule": { "oneOf": [ { "description": "Only in vaults with registration enabled. See the molecule endpoint in vaults without registration.", "properties": { "cxsmiles": { "type": "string" }, "duplicate_resolution": { "description": "Originally, only tautomer resolution was enabled via the api. For this reason, tautomer_resolution is still an acceptable synonym for duplicate_resolution.\nIf a duplicate, ambiguous OR, or tautomeric structure is detected, this parameter allows to decide the action. New will always create a new molecule, first will pick the first\nmolecule matching.\n\nTo manage cases where duplicate, ambiguous OR, or tautomeric structures might be detected when registering new Molecules/Batches, use the \"duplicate_resolution\" parameter within the Molecule section of the JSON parameters.\n\n first\n \"duplicate_resolution\":\"first\"\n results in a new Batch being registered for the first Molecule detected as a potential match\n new\n \"duplicate_resolution\":\"new\"\n results in a new Molecule being registered\n prompt\n \"duplicate_resolution\":\"prompt\"\n results in nothing being registered\n potentially matching molecule IDs are returned\ni The intent of the \"duplicate_resolution\":\"prompt\" parameter is to give you the Molecule IDs of the potentially matching structures… then, you can use the POST Batches without the structure, and match on the Molecule ID or Name to register the new Batch of any existing Molecule.\n", "enum": [ "first", "new", "prompt" ], "type": "string" }, "id": { "description": "The id of an existing molecule", "type": "integer" }, "name": { "type": "string" }, "registration_type": { "enum": [ "CHEMICAL_STRUCTURE" ], "type": "string" }, "smiles": { "type": "string" }, "structure": { "type": "string" } }, "type": "object" }, { "description": "When registering a new amino acid", "properties": { "amino_acid": { "description": "Amino acid code", "type": "string" }, "registration_type": { "enum": [ "AMINO_ACID" ], "type": "string" } }, "type": "object" }, { "description": "When registering a new nucleotide", "properties": { "nucleotide": { "description": "Nucleotide code", "type": "string" }, "registration_type": { "enum": [ "NUCLEOTIDE" ], "type": "string" } }, "type": "object" } ] }, "name": { "example": "Batch 1", "type": "string" }, "projects": { "description": "An array of project ids or names", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "salt_name": { "description": "A two-letter code or Salt vendor string as listed in the All Available Salts table (https://app.collaborativedrug.com/support/salts). The salt is determined automatically when the salt is included in the molecular structure.", "type": "string" }, "solvent_of_crystallization_name": { "description": "Name of the solvent of crystallization. List available at https://support.collaborativedrug.com/hc/en-us/articles/214359563-Salts-and-solvent-of-crystallization#solvents_of_crystallization", "type": "string" }, "stoichiometry": { "description": "Only in registration vaults", "properties": { "core_count": { "type": "integer" }, "salt_count": { "type": "integer" }, "solvent_of_crystallization_count": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "project_id_name": { "properties": { "id": { "example": 1, "type": "integer" }, "name": { "example": "Project 1", "type": "string" } }, "type": "object" }, "batch": { "properties": { "batch_fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "class": { "example": "batch", "type": "string" }, "created_at": { "format": "date", "type": "string" }, "formula_weight": { "type": "number" }, "id": { "example": 42, "type": "integer" }, "modified_at": { "format": "date", "type": "string" }, "molecule": { "properties": { "class": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "projects": { "items": { "$ref": "#/components/schemas/project_id_name" }, "type": "array" }, "registration_type": { "type": "string" }, "synonyms": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "molecule_batch_identifier": { "example": "DEMO-1000211-001", "type": "string" }, "name": { "example": "Batch 1", "type": "string" }, "owner": { "example": "Charlie Weatherall", "type": "string" }, "projects": { "items": { "$ref": "#/components/schemas/project_id_name" }, "type": "array" }, "salt_name": { "type": "string" }, "solvent_of_crystallization_name": { "type": "string" }, "stoichiometry": { "properties": { "core_count": { "type": "integer" }, "salt_count": { "type": "integer" }, "solvent_of_crystallization_count": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "date": { "description": "Notes on Date/Time Formats The CDD Vault API accepts ISO 8601 date/time formats in any API call that allows a date-type parameter. For example, the full date and timestamp may be used in GET calls that support a date parameter. You may still simply provide a date-only parameter like \"created_after=2020-05-20\". You may also specify a date + timestamp, like \"created_after= 2020-05-20 14:53:12\", to indicate \"20 May 2020 14:53:12 PDT\" (PDT is based on the user's time zone setting). The timestamp portion can also include a UTC (Coordinated Universal Time) offset, like \"created_after= 2020-05-27T14:48:40-07:00\" which indicates that the time specified is -7 hours from the UTC time.\n", "format": "date", "type": "string" }, "protocol_criterion": { "description": "A single protocol-based filter, used in the `protocol_criteria` array to restrict results to molecules/batches that have (or lack) particular protocol readout data. Combine multiple criteria with the `junction` field.", "properties": { "protocol_id": { "description": "Id of the protocol to filter on (provide this or `data_set_id`).", "type": "integer" }, "data_set_id": { "description": "Id of the data set to filter on (provide this or `protocol_id`).", "type": "integer" }, "run_criterion": { "description": "Which runs to consider.", "enum": [ "any", "recent", "run_date", "run_id" ], "type": "string" }, "run_id": { "description": "Run id to match (when `run_criterion` is `run_id`).", "type": "integer" }, "run_after": { "description": "Include runs on/after this date (when `run_criterion` is `run_date`).", "format": "date", "type": "string" }, "run_before": { "description": "Include runs on/before this date (when `run_criterion` is `run_date`).", "format": "date", "type": "string" }, "since_days_ago": { "description": "Number of days back to include (when `run_criterion` is `recent`).", "type": "integer" }, "readout_definition_id": { "description": "Id of the readout definition to filter on.", "type": "integer" }, "operator": { "description": "Comparison operator applied to `readout_value`.", "enum": [ "=", "!=", "<", ">", "≤", "≥", "contains", "does not contain", "from" ], "type": "string" }, "readout_value": { "description": "Value to compare the readout against.", "type": "string" }, "readout_value_maximum": { "description": "Upper bound of a range (when `operator` is `from`).", "type": "string" }, "calculation_error_type": { "description": "Filter by calculation error type.", "type": "string" }, "criterion_type": { "description": "The kind of protocol criterion.", "enum": [ "data set or protocol", "run date", "protocol field" ], "type": "string" }, "field": { "description": "Protocol field name (when `criterion_type` is `protocol field`).", "type": "string" }, "query": { "description": "Protocol field search value (when `criterion_type` is `protocol field`).", "type": "string" }, "protocol_condition_ids": { "description": "Restrict to these protocol condition ids.", "items": { "type": "integer" }, "type": "array" }, "negated": { "default": false, "description": "If true, exclude rather than include matches.", "type": "boolean" }, "junction": { "default": "AND", "description": "How to combine this criterion with the previous one (ignored for the first criterion).", "enum": [ "AND", "OR" ], "type": "string" } }, "type": "object" }, "structure_criterion": { "description": "A structure-property filter object. Each property is filtered by an optional `_minimum` and/or `_maximum` bound. Properties from different registration types (chemical, nucleotide, amino acid) cannot be mixed in one request. Only a representative subset of the available properties is listed below; all follow the same `_minimum` / `_maximum` convention.", "additionalProperties": true, "properties": { "heavy_atom_count_minimum": { "type": "integer" }, "heavy_atom_count_maximum": { "type": "integer" }, "cd_molweight_minimum": { "type": "number" }, "cd_molweight_maximum": { "type": "number" }, "exact_mass_minimum": { "type": "number" }, "exact_mass_maximum": { "type": "number" }, "log_p_minimum": { "type": "number" }, "log_p_maximum": { "type": "number" }, "log_d_minimum": { "type": "number" }, "log_d_maximum": { "type": "number" }, "log_s_minimum": { "type": "number" }, "log_s_maximum": { "type": "number" }, "num_aromatic_rings_minimum": { "type": "integer" }, "num_aromatic_rings_maximum": { "type": "integer" }, "num_h_bond_acceptors_minimum": { "type": "integer" }, "num_h_bond_acceptors_maximum": { "type": "integer" }, "num_h_bond_donors_minimum": { "type": "integer" }, "num_h_bond_donors_maximum": { "type": "integer" }, "num_rotatable_bonds_minimum": { "type": "integer" }, "num_rotatable_bonds_maximum": { "type": "integer" }, "num_rule_of_5_violations_minimum": { "type": "integer" }, "num_rule_of_5_violations_maximum": { "type": "integer" }, "topological_polar_surface_area_minimum": { "type": "number" }, "topological_polar_surface_area_maximum": { "type": "number" } }, "type": "object" }, "batch_query": { "properties": { "async": { "description": "If true, do an asynchronous export. Use for large data sets.", "type": "boolean" }, "batch_fields": { "description": "Array of Batch field names to include in the resulting JSON. Defaults to all available fields.", "items": { "type": "string" }, "type": "array" }, "created_after": { "$ref": "#/components/schemas/date" }, "collection_criteria": { "description": "Array of collection criteria objects. Filters results to only include batches whose molecules match the collection criteria, with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.", "items": { "type": "object", "required": [ "collection_id" ], "properties": { "collection_id": { "description": "The ID of the collection to filter by.", "type": "integer" }, "junction": { "description": "How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to \"AND\".", "type": "string", "enum": [ "AND", "OR", "XOR" ], "default": "AND" }, "not_in": { "description": "If true, excludes batches whose molecules belong to this collection instead of including them. Defaults to false.", "type": "boolean", "default": false } } }, "type": "array" }, "created_before": { "$ref": "#/components/schemas/date" }, "data_sets": { "description": "Array of public dataset ids. Defaults to all data sets.", "items": { "type": "integer" }, "type": "array" }, "fields_search": { "description": "Array of Batch field names & values. Used to filter Batches returned based on query values", "items": { "oneOf": [ { "properties": { "name": { "description": "Name of the field to search", "type": "string" }, "text_value": { "description": "Text value to search for", "type": "string" } }, "type": "object" }, { "properties": { "name": { "description": "Name of the field to search", "type": "string" }, "number_value": { "description": "Number value to search for", "type": "number" } }, "type": "object" }, { "properties": { "date_value": { "$ref": "#/components/schemas/date" }, "name": { "description": "Name of the field to search", "type": "string" } }, "type": "object" } ] }, "type": "array" }, "include_original_structures": { "default": false, "description": "If true, include the original structure in the response. This is independent of no_structures.", "type": "boolean" }, "modified_after": { "$ref": "#/components/schemas/date" }, "modified_before": { "$ref": "#/components/schemas/date" }, "molecule_batch_identifier": { "description": "A Molecule-Batch ID used to query the Vault. Use this parameter to limit the number of Molecule UDF Fields to return", "type": "string" }, "molecule_created_after": { "$ref": "#/components/schemas/date" }, "molecule_created_before": { "$ref": "#/components/schemas/date" }, "molecule_fields": { "description": "Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.", "items": { "type": "string" }, "type": "array" }, "no_structures": { "default": false, "description": "If true, omit structure representations for a smaller and faster response.", "type": "boolean" }, "offset": { "type": "integer" }, "only_ids": { "default": false, "description": "If true, only return the ids of the molecules in the batch.", "type": "boolean" }, "only_molecule_ids": { "default": false, "description": "If true, the full Batch details are still returned but the Molecule-level information is left out of the JSON results. (Only the IDs of the Molecules are still included.)", "type": "boolean" }, "page_size": { "default": 50, "description": "Requested page size (maximum value 1000).", "type": "integer" }, "projects": { "description": "Array of project ids. Defaults to all available projects.", "items": { "type": "integer" }, "type": "array" }, "protocol_criteria": { "description": "Array of protocol-based filters restricting results to batches with (or without) matching protocol readout data. Criteria are combined using each entry's `junction`.", "items": { "$ref": "#/components/schemas/protocol_criterion" }, "type": "array" }, "structure_criterion": { "$ref": "#/components/schemas/structure_criterion" } }, "type": "object" }, "batch_query_only_id": { "properties": { "batches": { "description": "Comma separated list of batch ids. Cannot be used with other parameters", "items": { "type": "integer" }, "type": "array" } }, "type": "object" }, "collection_create": { "properties": { "class": { "enum": [ "user collection" ], "example": "user collection", "type": "string" }, "created_at": { "format": "date", "type": "string" }, "modified_at": { "format": "date", "type": "string" }, "molecules": { "description": "The list of molecules in the collection.\n", "items": { "type": "integer" }, "type": "array" }, "name": { "example": "Rare compounds", "type": "string" }, "owner": { "example": "Jacob Bloom", "type": "string" } }, "type": "object" }, "collection": { "allOf": [ { "properties": { "id": { "description": "Id is also valid during creation/update but must match the id in the URL", "example": 42, "type": "integer" } }, "type": "object" }, { "$ref": "#/components/schemas/collection_create" } ] }, "collections_query_common": { "properties": { "async": { "description": "If true, do an asynchronous export. Use for large data sets. You will get an export id that you can use with the async export function.", "type": "boolean" }, "include_molecule_ids": { "description": "If true, include the ids of the molecules in the collection.", "type": "boolean" }, "offset": { "description": "The offset of the first collection in the result set. The offset is 0-based. That is, the first collection in the result set has offset 0.\n", "type": "integer" }, "only_ids": { "description": "If true, only return the ids of the matching collections.", "type": "boolean" }, "page_size": { "default": 50, "description": "The maximum number of objects to return in this call.\nDefault is 50, maximum is 1000. If the response exceeds the page_size,\nwe strongly recommend using the async option instead of downloading multiple chunks.\nNote: any page_size parameter used in an API call that also uses the async=true\nparameter will be ignored. The async call will return all valid data once executed.\n", "type": "integer" }, "projects": { "description": "Array of project ids. Defaults to all available projects.\n", "items": { "type": "integer" }, "type": "array" } }, "type": "object" }, "collections_query": { "oneOf": [ { "allOf": [ { "properties": { "collections": { "description": "The list of collections id to return\n", "type": "array", "items": { "type": "integer" } } }, "type": "object" }, { "$ref": "#/components/schemas/collections_query_common" } ] }, { "allOf": [ { "$ref": "#/components/schemas/collections_query_common" }, { "properties": { "created_after": { "$ref": "#/components/schemas/date" }, "created_before": { "$ref": "#/components/schemas/date" }, "modified_after": { "$ref": "#/components/schemas/date" }, "modified_before": { "$ref": "#/components/schemas/date" }, "type": { "description": "The type of collection user collections are private, vault collections are shared with project members.\n", "enum": [ "user_collection", "vault_collection" ], "type": "string" } }, "type": "object" } ] } ] }, "collection_update": { "properties": { "molecules": { "description": "The list of molecules to add to the collection. Note that you cannot remove molecules from a collection. You have to recreate the collection without the molecule.\n", "items": { "type": "integer" }, "type": "array" } }, "type": "object" }, "control_layout": { "description": "A control layout describes which wells of a protocol or run are controls (positive, negative, or a reference molecule).", "properties": { "class": { "example": "control layout", "type": "string" }, "control_wells": { "description": "The control wells defined by this layout.", "items": { "properties": { "col": { "description": "Zero-based column index of the well.", "type": "integer" }, "control_state": { "description": "The control type of the well: `+` (positive control), `-` (negative control), `#` (reference molecule), or an empty string (not a control).", "enum": [ "+", "-", "#", "" ], "type": "string" }, "row": { "description": "Zero-based row index of the well.", "type": "integer" } }, "type": "object" }, "type": "array" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "plate_id": { "description": "Id of the plate this layout applies to, when plate-specific.", "type": "integer" }, "protocol": { "description": "Id of the protocol the layout belongs to (always present for run-scoped layouts as the run's protocol).", "type": "integer" }, "run": { "description": "Id of the run the layout belongs to, when run-scoped.", "type": "integer" }, "size": { "description": "Number of wells in the layout (plate size).", "type": "integer" } }, "required": [ "id", "class", "size", "control_wells" ], "type": "object" }, "control_layout_create": { "description": "Attributes for creating a control layout. Specify the target with exactly one of `protocol` or `run`, and the layout dimensions with exactly one of `size` or `plate`.", "allOf": [ { "oneOf": [ { "required": [ "protocol" ] }, { "required": [ "run" ] } ] }, { "oneOf": [ { "required": [ "size" ] }, { "required": [ "plate" ] } ] } ], "example": { "protocol": 321, "size": 96, "control_wells": [ { "row": 0, "col": 0, "control_state": "+" }, { "pos": "H12", "control_state": "-" } ] }, "properties": { "control_wells": { "description": "The wells to mark as controls.", "items": { "properties": { "col": { "description": "Zero-based column index (use with `row`).", "type": "integer" }, "control_state": { "description": "Control type: `+` (positive), `-` (negative), `#` (reference molecule), or empty string (no control).", "enum": [ "+", "-", "#", "" ], "type": "string" }, "pos": { "description": "Well position in letter-number form (e.g. `A1`), as an alternative to `row`/`col`.", "type": "string" }, "row": { "description": "Zero-based row index (use with `col`).", "type": "integer" } }, "required": [ "control_state" ], "type": "object" }, "type": "array" }, "plate": { "description": "Id of the plate the layout applies to (alternative to `size`).", "type": "integer" }, "protocol": { "description": "Id of the protocol to attach the layout to.", "type": "integer" }, "run": { "description": "Id of the run to attach the layout to.", "type": "integer" }, "size": { "description": "Number of wells in the layout (alternative to `plate`).", "type": "integer" } }, "type": "object" }, "data_set": { "properties": { "id": { "description": "The id of the data_set\n", "type": "integer" }, "name": { "description": "The name of the data_set\n", "type": "string" } }, "type": "object" }, "eln_create": { "description": "Attributes used to create or update an ELN entry. The same body is accepted by `POST /eln/entries` (create) and `PUT /eln/entries/{id}` (update); on update, only the supplied fields are changed.\n", "example": { "title": "Synthesis of compound 42", "project": 7, "eln_fields": { "Reaction type": "Suzuki coupling" }, "append_to_body": [ { "type": "text", "text": "Procedure followed the standard protocol." }, { "type": "link", "url": "https://app.collaborativedrug.com/vaults/1/molecules/12345", "label": "Starting material CDD-12345" }, { "type": "file", "file": 98765 } ] }, "properties": { "append_to_body": { "description": "Ordered list of content nodes appended to the body of the entry. Each node has a `type`; the supported types are:\n\n- `text` — a paragraph of text. Provide `text` (defaults to an empty string).\n- `link` — a hyperlink. Provide `url` (required; must be a valid http/https/ftp/mailto URL) and an optional `label` for the display text. Use this to link to a batch, molecule, protocol, or any external resource.\n- `file` — an attachment that was already uploaded. Provide `file`, the id of an accessible uploaded file. (Files can also be attached to an existing entry with the `POST /files` API.)\n", "items": { "oneOf": [ { "title": "Text node", "properties": { "text": { "description": "Text content (defaults to an empty string).", "type": "string" }, "type": { "const": "text", "type": "string" } }, "required": [ "type" ], "type": "object" }, { "title": "Link node", "properties": { "label": { "description": "Display text for the link (optional).", "type": "string" }, "type": { "const": "link", "type": "string" }, "url": { "description": "Target URL (must be a valid http/https/ftp/mailto URL).", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, { "title": "File node", "properties": { "file": { "description": "Id of an already-uploaded, accessible file.", "type": "integer" }, "type": { "const": "file", "type": "string" } }, "required": [ "type", "file" ], "type": "object" } ] }, "type": "array" }, "eln_fields": { "additionalProperties": { "type": "string" }, "description": "The ELN fields of the entry\n", "type": "object" }, "project": { "anyOf": [ { "description": "Project id", "type": "integer" }, { "description": "Project name", "type": "string" } ] }, "title": { "description": "The title of the entry\n", "type": "string" } }, "type": "object" }, "eln_entry_status": { "properties": { "created_at": { "description": "Timestamp in ISO-8601 UTC", "example": "2024-01-02T03:04:05Z", "type": "string" }, "id": { "description": "The id of the entry\n", "example": 42, "type": "integer" }, "status": { "enum": [ "new", "open", "submitted", "finalized" ], "type": "string" }, "updated_at": { "description": "Timestamp in ISO-8601 UTC", "example": "2024-01-02T03:04:05Z", "type": "string" } }, "type": "object" }, "eln_entries_query": { "properties": { "async": { "default": false, "description": "Perform an asynchronous export\nIf true, do an asynchronous export (see Async Export)\nUse if you wish to retrieve a zip file containing exports of the actual ELN entries along with any files\nattached within the ELN entries. Note: any page_size parameter used in the call call that also uses the async=true parameter will be ignored. The call will return all matching entries as a zip file with their content.\n", "type": "boolean" }, "author": { "description": "List of ELN author IDs. We do not match by names, you need to use the users call.\n", "items": { "type": "string" }, "type": "array" }, "created_after": { "$ref": "#/components/schemas/date" }, "created_before": { "$ref": "#/components/schemas/date" }, "eln_entries": { "description": "List of ELN entry IDs", "items": { "type": "string" }, "type": "array" }, "finalized_date_after": { "$ref": "#/components/schemas/date" }, "finalized_date_before": { "$ref": "#/components/schemas/date" }, "modified_after": { "$ref": "#/components/schemas/date" }, "modified_before": { "$ref": "#/components/schemas/date" }, "offset": { "default": 0, "description": "Index of the first object actually returned", "type": "integer" }, "only_ids": { "default": false, "description": "Return only ELN Entry IDs", "type": "boolean" }, "only_summary": { "default": false, "description": "Return only a csv summary file, async is still recommended", "type": "boolean" }, "page_size": { "default": 50, "description": "Maximum number of objects to return in this call\nThis parameter is ignored is async is true.\n", "maximum": 1000, "type": "integer" }, "projects": { "description": "List of project IDs", "items": { "type": "string" }, "type": "array" }, "status": { "description": "Status of ELN entries (open, submitted, finalized)", "enum": [ "open", "submitted", "finalized" ], "type": "string" }, "submitted_date_after": { "$ref": "#/components/schemas/date" }, "submitted_date_before": { "$ref": "#/components/schemas/date" } }, "type": "object" }, "eln_status_action": { "description": "A witnessing/status action to perform on an ELN entry. The set of valid `status_action` values depends on whether ELN witnessing is enabled for the vault:\n\n- Witnessing enabled: `submit` (requires `witness`), `approve`, `reject` (requires `reason`), `cancel`, `reopen` (requires `reason`), `discard`.\n- Witnessing disabled: `finalize`, `reopen` (requires `reason`), `discard`.", "example": { "status_action": "submit", "witness": 6021 }, "properties": { "reason": { "description": "Reason for the action (required for `reject` and `reopen`).", "type": "string" }, "status_action": { "description": "The action to perform.", "enum": [ "submit", "approve", "reject", "cancel", "reopen", "finalize", "discard" ], "type": "string" }, "witness": { "description": "Id of the witnessing user (required for `submit`).", "type": "integer" } }, "required": [ "status_action" ], "type": "object" }, "export": { "properties": { "created_at": { "description": "Timestamp in ISO-8601 UTC", "example": "2024-01-02T03:04:05Z", "type": "string" }, "id": { "example": 1, "type": "integer" }, "modified_at": { "description": "Timestamp in ISO-8601 UTC", "example": "2024-01-02T03:04:05Z", "type": "string" }, "queued_job_position": { "description": "Position of the export's job in the processing queue. Only present while the export is in the `new` state.", "type": "integer" }, "status": { "description": "The export's state. While polling progress it moves `new` -> `started` -> `finished`; any value other than these three during polling means something went wrong. `canceled` is returned after a successful cancel.", "enum": [ "new", "started", "finished", "downloaded", "failed", "canceled" ], "type": "string" } }, "type": "object" }, "exports": { "items": { "$ref": "#/components/schemas/export" }, "type": "array" }, "file": { "properties": { "character_set": { "example": "US-ASCII", "type": "string" }, "class": { "example": "uploaded file", "type": "string" }, "contents": { "description": "Base64 encoded contents of the file", "example": "VGhpcyBpcyBhIGZpbGUK", "type": "string" }, "id": { "example": 1069448031, "type": "integer" }, "mime_type": { "properties": { "hash": { "example": -1147906696977776400, "type": "integer" }, "string": { "example": "text/plain", "type": "string" }, "symbol": { "example": "text", "type": "string" }, "synonyms": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "name": { "example": "tmp.txt", "type": "string" } }, "type": "object" }, "import_parser": { "description": "An import parser (plate block template) describing how a structured data file should be parsed during import.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "name": { "description": "Name of the import parser.", "type": "string" }, "owner": { "description": "Full name of the user who owns the import parser.", "type": "string" }, "template_json": { "additionalProperties": true, "description": "The parser configuration (arbitrary JSON object). Only returned by the show endpoint, not in the index listing.", "type": "object" } }, "required": [ "id", "name", "created_at", "modified_at", "owner" ], "type": "object" }, "inventory_location": { "properties": { "class": { "enum": [ "inventory location" ], "example": "inventory location", "type": "string" }, "created_at": { "example": "2023-10-30T18:25:41.771Z", "format": "date-time", "type": "string" }, "filled_position_count": { "example": 0, "type": "integer" }, "id": { "example": 42, "type": "integer" }, "modified_at": { "example": "2023-10-30T18:25:41.771Z", "format": "date-time", "type": "string" }, "num_columns": { "example": 0, "type": "integer" }, "num_rows": { "example": 0, "type": "integer" }, "parent_id": { "example": 130, "type": [ "null", "integer" ] }, "position_limit": { "example": 0, "type": "integer" }, "value": { "example": "Gotham", "type": "string" } }, "type": "object" }, "inventory_sample_object": { "description": "An inventory sample: a tracked physical amount of a batch, with its current amount, location, custom fields, and event history.", "properties": { "batch": { "description": "Id of the batch this sample is an inventory of.", "type": "integer" }, "batch_name": { "description": "Name of the associated batch.", "type": "string" }, "class": { "example": "inventory sample", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by_user_full_name": { "description": "Full name of the user who created the sample.", "type": "string" }, "current_amount": { "description": "Current amount remaining for the sample.", "type": "number" }, "depleted": { "description": "Whether the sample has been depleted.", "type": "boolean" }, "fields": { "additionalProperties": true, "description": "Custom inventory sample field values, keyed by field name.", "type": "object" }, "id": { "type": "integer" }, "inventory_events": { "description": "The event history (additions, withdrawals, etc.) for the sample.", "items": { "properties": { "class": { "example": "inventory event", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "fields": { "additionalProperties": true, "description": "Custom event field values, keyed by field name.", "type": "object" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "updated_by_user_full_name": { "type": "string" } }, "type": "object" }, "type": "array" }, "location": { "description": "Human-readable display path of the sample's location.", "type": "string" }, "modified_at": { "format": "date-time", "type": "string" }, "name": { "description": "Name (identifier) of the sample.", "type": "string" }, "units": { "description": "Units the sample amount is expressed in.", "type": "string" }, "updated_by_user_full_name": { "description": "Full name of the user who last modified the sample.", "type": "string" } }, "required": [ "id", "class", "created_at", "modified_at", "units", "batch", "batch_name", "current_amount", "depleted" ], "type": "object" }, "inventory_sample_create": { "description": "Attributes for creating an inventory sample.", "example": { "batch_id": 456, "units": "mg", "fields": { "Supplier": "Acme Chemicals" }, "inventory_events": [ { "fields": { "Credit": 100 } } ] }, "properties": { "batch_id": { "description": "Id of the batch this sample is an inventory of.", "type": "integer" }, "fields": { "additionalProperties": true, "description": "Custom inventory sample field values, keyed by field name.", "type": "object" }, "inventory_events": { "description": "Initial inventory event(s) for the sample. At most one event may be supplied per request.", "items": { "properties": { "fields": { "additionalProperties": true, "description": "Custom event field values, keyed by field name.", "type": "object" } }, "type": "object" }, "maxItems": 1, "type": "array" }, "units": { "description": "Units the sample amount is expressed in. One of: g, kg, mg, µg, ng, mL, L, µL, M, mM, µM, nM, mol, mmol, µmol, nmol, pmol, count.", "enum": [ "g", "kg", "mg", "µg", "ng", "mL", "L", "µL", "M", "mM", "µM", "nM", "mol", "mmol", "µmol", "nmol", "pmol", "count" ], "type": "string" } }, "required": [ "batch_id", "units" ], "type": "object" }, "inventory_sample_update": { "description": "Attributes for updating an inventory sample. Only supplied fields are changed.", "example": { "depleted": false, "fields": { "Supplier": "New Supplier Inc" }, "inventory_events": [ { "id": 54321, "fields": { "Debit": 10 } } ] }, "properties": { "depleted": { "description": "Mark the sample as depleted (`true`) or clear the depleted flag (`false`).", "type": "boolean" }, "fields": { "additionalProperties": true, "description": "Custom inventory sample field values, keyed by field name.", "type": "object" }, "inventory_events": { "description": "An inventory event to add or update. At most one event may be supplied per request. Include the event `id` to update an existing event; omit it to create a new one.", "items": { "properties": { "fields": { "additionalProperties": true, "description": "Custom event field values, keyed by field name.", "type": "object" }, "id": { "description": "Id of the event to update. Omit to create a new event.", "type": "integer" } }, "type": "object" }, "maxItems": 1, "type": "array" }, "units": { "description": "Units the sample amount is expressed in.", "enum": [ "g", "kg", "mg", "µg", "ng", "mL", "L", "µL", "M", "mM", "µM", "nM", "mol", "mmol", "µmol", "nmol", "pmol", "count" ], "type": "string" } }, "type": "object" }, "mapping_template_simple": { "properties": { "created_at": { "example": "2021-12-23T17:59:22.000-06:00", "format": "date-time", "type": "string" }, "id": { "example": 22704, "type": "integer" }, "modified_at": { "example": "2021-12-23T17:59:22.000-06:00", "format": "date-time", "type": "string" }, "name": { "example": "Protac Registration", "type": "string" }, "owner": { "example": "Charlie Weatherall", "type": "string" } }, "type": "object" }, "mapping_template_details": { "properties": { "created_at": { "example": "2021-12-23T17:59:22.000-06:00", "format": "date-time", "type": "string" }, "file": { "properties": { "file_name": { "type": "string" }, "value": { "type": "integer" } }, "type": "object" }, "header_mappings": { "items": { "properties": { "definition": { "properties": { "data_type_name": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "pick_list_values": { "items": { "type": "string" }, "type": "array" }, "protocol_name": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "header": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "run_grouping": { "type": "integer" } }, "type": "object" }, "type": "array" }, "id": { "example": 22704, "type": "integer" }, "modified_at": { "example": "2021-12-23T17:59:22.000-06:00", "format": "date-time", "type": "string" }, "name": { "example": "Protac Registration", "type": "string" }, "owner": { "example": "Charlie Weatherall", "type": "string" } }, "type": "object" }, "molecule_create": { "additionalProperties": true, "description": "Attributes for creating a molecule. Creating molecules directly is only allowed in vaults that are NOT using a registration system; in registration vaults, register molecules by creating batches instead.", "example": { "name": "My compound", "structure": "CC(=O)Oc1ccccc1C(=O)O", "synonyms": [ "Aspirin" ], "projects": [ 12 ], "molecule_fields": { "Solubility": "High" } }, "properties": { "collections": { "description": "Collections to add the molecule to (ids or names).", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "duplicate_resolution": { "description": "How to handle a structure that duplicates an existing molecule. `new` registers a new molecule; `prompt` fails with the duplicate details so the caller can decide. Must match `tautomer_resolution` if both are given.", "enum": [ "new", "prompt" ], "type": "string" }, "molecule_fields": { "additionalProperties": true, "description": "Custom molecule field values, keyed by field name. The legacy alias `udfs` is also accepted.", "type": "object" }, "name": { "description": "Name of the molecule.", "type": "string" }, "projects": { "description": "Projects the molecule belongs to (ids or names).", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "registration_form": { "description": "The registration form to use (id or name). Defaults to the vault default.", "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "registration_type": { "description": "The kind of entity being registered (e.g. CHEMICAL_STRUCTURE).", "type": "string" }, "structure": { "description": "The chemical structure, as SMILES or a molfile. For amino-acid, nucleotide, or mixture molecules use the corresponding structure representation accepted for that registration type.", "type": "string" }, "synonyms": { "description": "Alternative names for the molecule.", "items": { "type": "string" }, "type": "array" }, "tautomer_resolution": { "description": "How to handle a structure that is a tautomer of an existing molecule.", "enum": [ "new", "prompt" ], "type": "string" } }, "required": [ "name" ], "type": "object" }, "molecule": { "properties": { "batches": { "description": "Array of batches belonging to this molecule", "items": { "properties": { "batch_fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "class": { "example": "batch", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "formula_weight": { "type": "number" }, "id": { "example": 42, "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "molecule_batch_identifier": { "example": "DEMO-1000211-001", "type": "string" }, "name": { "example": "Batch 1", "type": "string" }, "owner": { "example": "Charlie Weatherall", "type": "string" }, "projects": { "items": { "$ref": "#/components/schemas/project_id_name" }, "type": "array" }, "salt_name": { "type": "string" }, "solvent_of_crystallization_name": { "type": "string" }, "stoichiometry": { "properties": { "core_count": { "type": "integer" }, "salt_count": { "type": "integer" }, "solvent_of_crystallization_count": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "class": { "example": "molecule", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "example": 1000211, "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "molecule_fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "name": { "example": "Aspirin", "type": "string" }, "owner": { "example": "Charlie Weatherall", "type": "string" }, "projects": { "items": { "$ref": "#/components/schemas/project_id_name" }, "type": "array" }, "registration_type": { "description": "The registration type of the molecule", "enum": [ "chemical_structure", "amino_acid", "nucleotide", "mixture", "other" ], "example": "chemical_structure", "type": "string" }, "smiles": { "description": "SMILES representation of the molecule structure", "example": "CC(=O)OC1=CC=CC=C1C(=O)O", "type": "string" }, "synonyms": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "molecule_query": { "properties": { "async": { "description": "If true, do an asynchronous export. Use for large data sets.", "type": "boolean" }, "batch_created_after": { "$ref": "#/components/schemas/date" }, "batch_created_before": { "$ref": "#/components/schemas/date" }, "batch_field_after_date": { "$ref": "#/components/schemas/date" }, "batch_field_after_name": { "description": "Name of the batch date field to filter on (used with batch_field_after_date).", "type": "string" }, "batch_field_before_date": { "$ref": "#/components/schemas/date" }, "batch_field_before_name": { "description": "Name of the batch date field to filter on (used with batch_field_before_date).", "type": "string" }, "batch_fields": { "description": "Array of Batch field names to include in the resulting JSON. Defaults to all available fields.", "items": { "type": "string" }, "type": "array" }, "collection_criteria": { "description": "Array of collection criteria objects. Filters results based on collection membership with support for AND/OR/XOR junctions and exclusion (NOT IN) logic.", "items": { "type": "object", "required": [ "collection_id" ], "properties": { "collection_id": { "description": "The ID of the collection to filter by.", "type": "integer" }, "junction": { "description": "How to combine this criterion with the previous one. The first criterion's junction is ignored. Defaults to \"AND\".", "type": "string", "enum": [ "AND", "OR", "XOR" ], "default": "AND" }, "not_in": { "description": "If true, excludes molecules that belong to this collection instead of including them. Defaults to false.", "type": "boolean", "default": false } } }, "type": "array" }, "created_after": { "$ref": "#/components/schemas/date" }, "created_before": { "$ref": "#/components/schemas/date" }, "data_sets": { "description": "Array of public dataset ids. Defaults to all data sets.", "items": { "type": "integer" }, "type": "array" }, "fields_search": { "description": "Array of Molecule field names & values. Used to filter Molecules returned based on query values", "items": { "oneOf": [ { "properties": { "name": { "description": "Name of the field to search", "type": "string" }, "text_value": { "description": "Text value to search for", "type": "string" } }, "type": "object" }, { "properties": { "name": { "description": "Name of the field to search", "type": "string" }, "number_value": { "description": "Number value to search for", "type": "number" } }, "type": "object" }, { "properties": { "date_value": { "$ref": "#/components/schemas/date" }, "name": { "description": "Name of the field to search", "type": "string" } }, "type": "object" } ] }, "type": "array" }, "include_original_structures": { "default": false, "description": "If true, include the original structure in the response. This is independent of no_structures.", "type": "boolean" }, "inchikey": { "description": "Filter molecules by InChIKey.", "type": "string" }, "modified_after": { "$ref": "#/components/schemas/date" }, "modified_before": { "$ref": "#/components/schemas/date" }, "molecule_fields": { "description": "Array of Molecule field names to include in the resulting JSON. Defaults to all available fields.", "items": { "type": "string" }, "type": "array" }, "names": { "description": "Array of molecule names or synonyms to search for.", "items": { "type": "string" }, "type": "array" }, "no_structures": { "default": false, "description": "If true, omit structure representations for a smaller and faster response.", "type": "boolean" }, "offset": { "type": "integer" }, "only_batch_ids": { "default": false, "description": "If true, the full Molecule details are still returned but the Batch-level information is left out of the JSON results. (Only the IDs of the Batches are still included.)", "type": "boolean" }, "only_ids": { "default": false, "description": "If true, only return the ids of the molecules.", "type": "boolean" }, "page_size": { "default": 50, "description": "Requested page size (maximum value 1000).", "type": "integer" }, "projects": { "description": "Array of project ids. Defaults to all available projects.", "items": { "type": "integer" }, "type": "array" }, "protocol_criteria": { "description": "Array of protocol-based filters restricting results to molecules with (or without) matching protocol readout data. Criteria are combined using each entry's `junction`.", "items": { "$ref": "#/components/schemas/protocol_criterion" }, "type": "array" }, "structure": { "description": "A SMILES or MOL string to search for.", "type": "string" }, "structure_criterion": { "$ref": "#/components/schemas/structure_criterion" }, "structure_search_type": { "description": "The type of structure search to perform. Options are 'exact', 'substructure', 'similarity', or 'exact_with_stereo'.", "enum": [ "exact", "substructure", "similarity", "exact_with_stereo" ], "type": "string" }, "structure_similarity_threshold": { "description": "Similarity threshold for similarity searches (0 to 1). Only used when structure_search_type is 'similarity'.", "maximum": 1, "minimum": 0, "type": "number" } }, "type": "object" }, "molecule_query_only_id": { "properties": { "molecules": { "description": "Comma separated list of molecule ids. Cannot be used with other parameters", "items": { "type": "integer" }, "type": "array" } }, "type": "object" }, "molecule_update": { "additionalProperties": true, "description": "Attributes for updating a molecule. Only the supplied fields are changed. Array fields (`synonyms`, `projects`, `collections`) replace the existing values.", "example": { "name": "Renamed compound", "synonyms": [ "Aspirin", "2-Acetoxybenzoic acid" ], "molecule_fields": { "Solubility": "Medium" } }, "properties": { "collections": { "description": "Collections the molecule belongs to (ids or names). Replaces existing.", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "molecule_fields": { "additionalProperties": true, "description": "Custom molecule field values, keyed by field name. The legacy alias `udfs` is also accepted.", "type": "object" }, "name": { "description": "Name of the molecule.", "type": "string" }, "projects": { "description": "Projects the molecule belongs to (ids or names). Replaces existing.", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "structure": { "description": "Updated chemical structure, as SMILES or a molfile.", "type": "string" }, "synonyms": { "description": "Alternative names for the molecule. Replaces existing.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "plate_object": { "description": "A plate of wells, optionally associated with batches/samples and run statistics.", "properties": { "class": { "example": "plate", "type": "string" }, "concentration": { "type": "number" }, "concentration_unit_label": { "description": "Units for `concentration` (e.g. \"M\").", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "inventory_location_id": { "type": "integer" }, "location": { "description": "Free-text location of the plate.", "type": "string" }, "modified_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "projects": { "description": "Projects the plate belongs to.", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "statistics": { "description": "Per-run plate statistics (Z'-factor, control means, etc.).", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "volume": { "type": "number" }, "volume_unit_label": { "description": "Units for `volume` (e.g. \"µL\").", "type": "string" }, "wells": { "description": "The wells of the plate and their batch/sample assignments.", "items": { "additionalProperties": true, "properties": { "batch": { "description": "Batch id in the well (if any).", "type": "integer" }, "col": { "description": "Zero-based column index.", "type": "integer" }, "row": { "description": "Zero-based row index.", "type": "integer" }, "sample": { "description": "Inventory sample id in the well (if any).", "type": "integer" } }, "type": "object" }, "type": "array" } }, "required": [ "id", "class", "name" ], "type": "object" }, "plate_create_update": { "description": "Attributes for creating or updating a plate. On create, `name` and `projects` are required. Supplying `wells` replaces the plate's wells.", "example": { "name": "Plate 001", "projects": [ 12 ], "location": "Freezer A", "wells": [ { "row": 0, "col": 0, "batch": 456 } ] }, "properties": { "concentration": { "type": "number" }, "concentration_unit_label": { "type": "string" }, "inventory_location": { "description": "Id of the inventory location for the plate.", "type": "integer" }, "location": { "type": "string" }, "name": { "type": "string" }, "projects": { "description": "Project ids the plate belongs to.", "items": { "type": "integer" }, "type": "array" }, "volume": { "type": "number" }, "volume_unit_label": { "type": "string" }, "wells": { "description": "Wells to populate. Each well identifies its position by `row`+`col` or `pos`.", "items": { "properties": { "batch": { "description": "Batch id to place in the well.", "type": "integer" }, "col": { "type": "integer" }, "pos": { "description": "Well position in letter-number form (e.g. \"A1\"), as an alternative to row/col.", "type": "string" }, "row": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "project_object": { "description": "A project in the vault. The list (index) and create responses contain only `id` and `name`; the show and update responses additionally include `description` and `members`.", "properties": { "description": { "description": "Project description (present in show/update responses).", "type": "string" }, "id": { "type": "integer" }, "members": { "description": "Project members and their permissions (present in show/update responses).", "items": { "additionalProperties": true, "properties": { "can_edit_data": { "type": "boolean" }, "can_manage_project": { "type": "boolean" }, "id": { "description": "User id.", "type": "integer" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "project_create_update_public": { "description": "Attributes for creating or updating a project.", "example": { "name": "My project", "description": "Compounds from the 2026 screening campaign", "members": [ { "user_id": 6021, "can_manage_project": true, "can_edit_data": true } ] }, "properties": { "description": { "description": "Project description.", "type": "string" }, "members": { "description": "Project members. On update this replaces the existing membership list. If omitted on create, the current user is added as a member.", "items": { "properties": { "can_edit_data": { "default": false, "type": "boolean" }, "can_manage_project": { "default": false, "type": "boolean" }, "user_id": { "description": "Id of an existing vault user.", "type": "integer" } }, "required": [ "user_id" ], "type": "object" }, "type": "array" }, "name": { "description": "Project name (must be unique within the vault).", "type": "string" } }, "required": [ "name" ], "type": "object" }, "protocol_object": { "description": "A protocol (assay definition) and its readout definitions, calculations, and runs.", "properties": { "calculations": { "description": "Calculation definitions on the protocol.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "category": { "description": "Value of the Category protocol field, echoed at top level when present.", "type": "string" }, "class": { "example": "protocol", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "data_set": { "description": "Id of the data set the protocol belongs to.", "type": "integer" }, "description": { "description": "Value of the Description protocol field, echoed at top level when present.", "type": "string" }, "hit_definitions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "ontology_annotations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "owner": { "description": "Full name of the protocol owner.", "type": "string" }, "projects": { "description": "Project ids the protocol belongs to.", "items": { "type": "integer" }, "type": "array" }, "protocol_fields": { "additionalProperties": true, "description": "Custom protocol field values, keyed by field name.", "type": "object" }, "protocol_statistics": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "readout_definitions": { "description": "The readout definitions of the protocol.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "runs": { "description": "Runs of the protocol. Omitted when the request passes `no_runs=true`.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "id", "class", "name" ], "type": "object" }, "protocol_update": { "description": "Attributes for updating a protocol's definition (not its readout definitions). Only the supplied fields are changed.", "example": { "name": "My Inhibition Screen", "projects": [ 12 ], "protocol_fields": { "Category": "Biochemical" } }, "properties": { "name": { "type": "string" }, "projects": { "description": "Project ids the protocol belongs to (replaces the existing set).", "items": { "type": "integer" }, "type": "array" }, "protocol_fields": { "additionalProperties": true, "description": "Custom protocol field values, keyed by field name.", "type": "object" } }, "type": "object" }, "readout_row_query": { "properties": { "async": { "description": "If true, do an asynchronous export. Use for large data sets.", "type": "boolean" }, "batches": { "description": "Array of batch ids. Defaults to all batches.", "items": { "type": "integer" }, "type": "array" }, "created_after": { "$ref": "#/components/schemas/date" }, "created_before": { "$ref": "#/components/schemas/date" }, "data_sets": { "description": "Array of public dataset ids. Defaults to all data sets.", "items": { "type": "integer" }, "type": "array" }, "include_control_state": { "default": false, "description": "If true, include the control state of each readout.", "type": "boolean" }, "modified_after": { "$ref": "#/components/schemas/date" }, "modified_before": { "$ref": "#/components/schemas/date" }, "molecules": { "description": "Array of molecule ids. Defaults to all molecules.", "items": { "type": "integer" }, "type": "array" }, "offset": { "type": "integer" }, "only_ids": { "default": false, "description": "If true, only return the ids of the readout rows.", "type": "boolean" }, "page_size": { "default": 50, "description": "Requested page size (maximum value 1000).", "type": "integer" }, "plates": { "description": "Array of plate ids. Defaults to all plates.", "items": { "type": "integer" }, "type": "array" }, "projects": { "description": "Array of project ids. Defaults to all available projects.", "items": { "type": "integer" }, "type": "array" }, "protocols": { "description": "Array of protocol ids. Defaults to all protocols.", "items": { "type": "integer" }, "type": "array" }, "runs": { "description": "Array of run ids. Defaults to all runs.", "items": { "type": "integer" }, "type": "array" }, "runs_after": { "$ref": "#/components/schemas/date" }, "runs_before": { "$ref": "#/components/schemas/date" }, "type": { "description": "Filter to specific readout row types. Defaults to all types.", "items": { "enum": [ "detail_row", "batch_run_aggregate_row", "batch_protocol_aggregate_row", "molecule_protocol_aggregate_row" ], "type": "string" }, "type": "array" } }, "type": "object" }, "readout_row": { "properties": { "batch": { "description": "ID of the batch this readout row belongs to", "example": 1, "type": "integer" }, "class": { "example": "readout row", "type": "string" }, "created_at": { "description": "Timestamp in ISO-8601 UTC", "example": "2024-01-02T03:04:05Z", "type": "string" }, "id": { "example": 1, "type": "integer" }, "modified_at": { "description": "Timestamp in ISO-8601 UTC", "example": "2024-01-02T03:04:05Z", "type": "string" }, "molecule": { "description": "ID of the molecule this readout row belongs to", "example": 1, "type": "integer" }, "protocol": { "description": "ID of the protocol this readout row belongs to", "example": 1, "type": "integer" }, "readouts": { "additionalProperties": true, "description": "Readout values keyed by readout definition ID", "type": "object" }, "run": { "description": "ID of the run this readout row belongs to", "example": 1, "type": "integer" }, "type": { "enum": [ "detail_row", "batch_run_aggregate_row", "batch_protocol_aggregate_row", "molecule_protocol_aggregate_row" ], "type": "string" }, "well": { "description": "Well position for plate-based data", "type": "string" } }, "type": "object" }, "registration_form": { "description": "A registration form configured in the vault.", "properties": { "allow_new_molecules": { "description": "Whether the form permits registering new molecules.", "type": "boolean" }, "class": { "example": "registration form", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "registration_system": { "description": "The registration system the form belongs to. Present only when the form is associated with a registration system.", "properties": { "class": { "example": "registration system", "type": "string" }, "id": { "type": "integer" } }, "type": "object" }, "registration_type": { "description": "The kind of entity this form registers.", "type": "string" } }, "required": [ "id", "name", "registration_type", "allow_new_molecules", "created_at", "modified_at", "class" ], "type": "object" }, "public_registration_system": { "description": "A registration system defined in the vault.", "properties": { "id": { "type": "integer" }, "prefix": { "description": "The registration id prefix used by this system.", "example": "CDD", "type": "string" } }, "required": [ "id", "prefix" ], "type": "object" }, "run_object": { "description": "A run of a protocol (a set of readout data collected on a date).", "properties": { "attached_files": { "description": "Files attached to the run.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "class": { "example": "run", "type": "string" }, "conditions": { "description": "Value of the Conditions run field, echoed at top level for convenience.", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "eln_entries": { "description": "ELN entries associated with the run.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "ontology_annotations": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "person": { "description": "Value of the Person run field, echoed at top level for convenience.", "type": "string" }, "place": { "description": "Value of the Lab run field, echoed at top level for convenience.", "type": "string" }, "plate_statistics": { "description": "Per-plate statistics for the run. Only included in the show response.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "project": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "protocol": { "description": "Id of the protocol the run belongs to.", "type": "integer" }, "run_date": { "format": "date", "type": "string" }, "run_fields": { "additionalProperties": true, "description": "Custom run field values, keyed by field name.", "type": "object" }, "source_files": { "description": "Source files the run was imported from.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "id", "class", "run_date", "project", "protocol" ], "type": "object" }, "run_update": { "description": "Attributes for updating a run. Only the supplied fields are changed.", "example": { "run_date": "2026-01-15", "run_fields": { "Person": "Jane Smith" } }, "properties": { "conditions": { "description": "Value for the Conditions run field (alternative to `run_fields`).", "type": "string" }, "person": { "description": "Value for the Person run field (alternative to `run_fields`).", "type": "string" }, "place": { "description": "Value for the Lab run field (alternative to `run_fields`).", "type": "string" }, "project_id": { "description": "Move the run to this project (requires write access to the target project).", "type": "integer" }, "run_date": { "format": "date", "type": "string" }, "run_fields": { "additionalProperties": true, "description": "Custom run field values, keyed by field name.", "type": "object" } }, "type": "object" }, "saved_search_session": { "description": "A saved search, including its full search criteria and display settings. Fields whose value is empty are omitted from the response.", "properties": { "display_criteria": { "additionalProperties": true, "description": "Display/column settings saved with the search.", "properties": { "custom_displayed_header_ids": { "items": {}, "type": "array" }, "displayed_header_ids": { "items": {}, "type": "array" }, "header_group_order": { "items": {}, "type": "array" }, "image_size": { "type": "string" }, "max_column_width": { "type": "integer" }, "plot_scale_type": { "type": "string" }, "row_detail_level": { "type": "string" }, "show_all_protocol_data": { "type": "boolean" }, "show_dose_response_legend": { "type": "boolean" }, "show_non_matching_readouts": { "type": "boolean" } }, "type": "object" }, "executed_by": { "description": "Names of users who have run the search.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "The saved search id.", "type": "integer" }, "last_api_run_at": { "format": "date-time", "type": "string" }, "last_ui_run_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "owner": { "description": "The search owner's name.", "type": "string" }, "projects": { "description": "Projects the search is scoped to.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "saved_search_session_id": { "type": "integer" }, "search_criteria": { "description": "The full criteria that define the search.", "properties": { "collection_criteria": { "items": { "properties": { "collection_id": { "type": "integer" }, "junction": { "enum": [ "AND", "OR", "XOR" ], "type": "string" }, "not_in": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "keyword_field": { "type": "string" }, "keywords": { "type": "string" }, "molecule_criteria": { "description": "Molecule property criteria.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "protocol_criteria": { "items": { "$ref": "#/components/schemas/protocol_criterion" }, "type": "array" }, "sort_direction": { "enum": [ "ASC", "DESC" ], "type": "string" }, "structure": { "description": "The query structure (SMILES/MOL), when a structure search is saved.", "type": "string" }, "structure_criterion": { "$ref": "#/components/schemas/structure_criterion" }, "structure_registration_type": { "enum": [ "structure", "nucleotide_sequence", "amino_acid_sequence" ], "type": "string" }, "structure_search_type": { "type": "string" }, "structure_similarity_threshold": { "type": "number" } }, "type": "object" }, "visualization_session_id": { "type": "integer" } }, "required": [ "id", "name", "search_criteria" ], "type": "object" }, "slurp": { "description": "A slurp is an asynchronous data import/processing job. After creation a slurp moves through processing and committing states until its data is committed to the vault.", "properties": { "ambiguous_events": { "description": "Ambiguous events raised during import. Only present when `show_events=true`.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "ambiguous_events_count": { "description": "Number of ambiguous events. Only present when `show_events=true`.", "type": "integer" }, "api_url": { "description": "Canonical API URL of this slurp.", "type": "string" }, "class": { "example": "slurp", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "import_errors": { "description": "When `show_events=true`, the array of import error events; otherwise the count of import errors.", "oneOf": [ { "type": "integer" }, { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } ] }, "import_errors_count": { "description": "Number of import errors. Only present when `show_events=true`.", "type": "integer" }, "import_warnings": { "description": "Count of import warnings. Present when `show_events` is not requested.", "type": "integer" }, "message": { "description": "Present when the slurp has unresolved import errors or warnings that must be resolved in the web application.", "type": "string" }, "modified_at": { "format": "date-time", "type": "string" }, "queued_job_position": { "description": "Position of the slurp's job in the queue. Present only while queued.", "type": "integer" }, "queued_slurp_position": { "description": "Position of the slurp among queued slurps. Present only while queued.", "type": "integer" }, "records_committed": { "description": "Number of records committed so far.", "type": "number" }, "records_processed": { "description": "Number of records processed so far.", "type": "number" }, "state": { "description": "Current state of the slurp.", "enum": [ "mapping", "queued_for_processing", "processing", "processed", "queued_for_committing", "committing", "committed", "canceled", "rejected", "invalid" ], "type": "string" }, "suspicious_events": { "description": "Suspicious events raised during import. Only present when `show_events=true`.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "suspicious_events_count": { "description": "Number of suspicious events. Only present when `show_events=true`.", "type": "integer" }, "total_records": { "description": "Total number of records in the imported file.", "type": "number" }, "web_url": { "description": "Web application URL for resolving import errors/warnings. Accompanies `message` when present.", "type": "string" } }, "required": [ "id", "class", "created_at", "modified_at", "state", "api_url" ], "type": "object" }, "vault_status": { "description": "Operational status of the vault: running imports (slurps), recalculating protocols, and overall application availability. Requires vault administrator access.", "properties": { "any_executing_batch_move_job": { "description": "Whether any batch move job is currently executing.", "type": "boolean" }, "any_locking_chemistry_slurps": { "description": "Whether any running slurp is currently holding the chemistry lock (which blocks chemistry recalculation).", "type": "boolean" }, "application_status": { "description": "Overall availability of the background processing services.", "properties": { "calculators_available": { "description": "Whether calculation processors are available.", "type": "boolean" }, "downtime_expected": { "description": "Present only when scheduled downtime has been announced.", "properties": { "end": { "description": "When the downtime is expected to end.", "format": "date-time", "type": "string" }, "reason": { "description": "Human-readable explanation of the downtime.", "type": "string" }, "start": { "description": "When the downtime is expected to start.", "format": "date-time", "type": "string" } }, "type": "object" }, "processors_available": { "description": "Whether import/data processors are available.", "type": "boolean" } }, "required": [ "processors_available", "calculators_available" ], "type": "object" }, "max_executing_account_slurps": { "description": "Maximum number of slurps the account may run concurrently.", "type": "integer" }, "num_executing_account_slurps": { "description": "Number of slurps currently executing across the account.", "type": "integer" }, "recalculating_protocols": { "description": "Protocols whose data is currently being recalculated.", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "projects": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "slurps": { "description": "Slurps (imports) that are currently active in the vault.", "items": { "properties": { "chemistry_locking": { "description": "Whether this slurp is holding the chemistry lock.", "type": "boolean" }, "id": { "type": "integer" }, "modified_at": { "format": "date-time", "type": "string" }, "owner": { "properties": { "email": { "type": "string" }, "first_name": { "type": "string" }, "id": { "type": "integer" }, "last_name": { "type": "string" } }, "type": "object" }, "project": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "state": { "description": "Current state of the slurp. Only active slurps are listed, so the state is one of the active states below (queued slurps appear here once they exceed the account's concurrent-processing limit).", "enum": [ "queued_for_processing", "processing", "processed", "queued_for_committing", "committing" ], "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "max_executing_account_slurps", "num_executing_account_slurps", "any_locking_chemistry_slurps", "any_executing_batch_move_job", "slurps", "recalculating_protocols", "application_status" ], "type": "object" }, "protocol_id": { "description": "Numeric identifier of the protocol", "type": "integer" }, "fit_parameter_constraint": { "description": "A constraint for a fit parameter", "type": "object", "properties": { "modifier": { "description": "The type of constraint. Valid values are: \"=\" (fixed), \">\", \">=\", \"<\", \"<=\", \"from\" (range), \"best fit\" (unconstrained, data series only).\n", "type": [ "null", "string" ], "example": "=" }, "value": { "description": "The constraint value. Required when modifier is \"=\", \">\", \">=\", \"<\", or \"<=\".", "type": [ "null", "number" ], "example": 0.5 }, "range": { "description": "Range constraint with min and max values. Used when modifier is \"from\".\n", "type": "object", "properties": { "min": { "description": "The minimum value of the range", "type": "number", "example": 0 }, "max": { "description": "The maximum value of the range", "type": "number", "example": 100 } } } } }, "fit_parameters": { "description": "Fit parameter constraints for curve fitting calculations. The available\nparameters depend on the calculation's equation_type:\n- Hill: min, max, slope\n- Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2\n- Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2\n- Linear: slope, y_intercept\n- Exponential Decay: c_0, c_min, k\n- Michaelis-Menten: b_max, k_d\n", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/fit_parameter_constraint" }, "example": { "min": { "modifier": "=", "value": 0 }, "max": { "modifier": ">=", "value": 100 } } }, "minimum_activity": { "description": "Minimum activity (inactivity) bounds for dose response calculations", "type": "object", "properties": { "lower": { "description": "The lower bound for the inactive range", "type": [ "null", "number" ], "example": 10 }, "upper": { "description": "The upper bound for the inactive range", "type": [ "null", "number" ], "example": 90 } } }, "calculation": { "description": "A protocol calculation", "type": "object", "properties": { "id": { "description": "The unique identifier of the calculation", "type": "integer", "example": 12345 }, "class": { "description": "The type of calculation. Values include \"dose response calculation\", \"custom calculation\", \"normalized calculation\", etc.\n", "type": "string", "example": "dose response calculation" }, "inputs": { "description": "The input readout definitions used by this calculation", "type": "object" }, "outputs": { "description": "The output readout definitions produced by this calculation", "type": "object" }, "fit_parameters": { "$ref": "#/components/schemas/fit_parameters", "description": "Fit parameter constraints (only for dose response calculations)" }, "minimum_activity": { "$ref": "#/components/schemas/minimum_activity", "description": "Minimum activity bounds (only for dose response calculations)" } } }, "calculations_list": { "description": "A list of calculations for a protocol", "type": "object", "properties": { "objects": { "description": "The list of calculations", "type": "array", "items": { "$ref": "#/components/schemas/calculation" } }, "count": { "description": "The total number of calculations", "type": "integer", "example": 5 } } }, "dose_response_calculation_id": { "description": "Numeric identifier of the dose response calculation", "type": "integer" }, "calculation_update": { "description": "Request body for updating a dose response calculation", "type": "object", "properties": { "fit_parameters": { "description": "Fit parameter constraints for the calculation. Setting this to an empty object\nclears all constraints. The available parameters depend on the calculation's\nequation_type:\n- Hill: min, max, slope\n- Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2\n- Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2\n- Linear: slope, y_intercept\n- Exponential Decay: c_0, c_min, k\n- Michaelis-Menten: b_max, k_d\n", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/fit_parameter_constraint" } }, "minimum_activity": { "description": "Minimum activity (inactivity) bounds", "type": "object", "properties": { "lower": { "description": "The lower bound for the inactive range", "type": [ "null", "number" ], "example": 10 }, "upper": { "description": "The upper bound for the inactive range", "type": [ "null", "number" ], "example": 90 }, "modifier": { "description": "The modifier type. If not specified, it is inferred from the bounds (\">\", \"<\", or \"from\" for range).\n", "type": "string", "example": "from" } } } } }, "dose_response_data_series": { "description": "A dose response data series representing curve data for a specific batch/run", "type": "object", "properties": { "id": { "description": "The unique identifier of the data series", "type": "integer", "example": 67890 }, "fit_parameters": { "$ref": "#/components/schemas/fit_parameters", "description": "Fit parameter constraints specific to this data series" }, "updated_at": { "description": "Timestamp of last update in ISO-8601 UTC format", "type": "string", "example": "2026-01-30T14:42:24Z" } } }, "dose_response_data_series_list": { "description": "A list of data series for a calculation", "type": "object", "properties": { "objects": { "description": "The list of data series", "type": "array", "items": { "$ref": "#/components/schemas/dose_response_data_series" } }, "count": { "description": "The total number of data series", "type": "integer", "example": 10 } } }, "dose_response_data_series_id": { "description": "Numeric identifier of the dose response data series", "type": "integer" }, "dose_response_data_series_update": { "description": "Request body for updating a data series", "type": "object", "properties": { "fit_parameters": { "description": "Fit parameter constraints for this data series. These override the\ncalculation-level constraints for this specific curve. The available\nparameters depend on the calculation's equation_type:\n- Hill: min, max, slope\n- Biphasic: center1, center2, frac, plateau1, plateau2, slope1, slope2\n- Bell Curve: plateau1, center1, slope1, peak, center2, slope2, plateau2\n- Linear: slope, y_intercept\n- Exponential Decay: c_0, c_min, k\n- Michaelis-Menten: b_max, k_d\nData series support \"best fit\" modifier for unconstrained fitting.\n", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/fit_parameter_constraint" } } } }, "errors": { "properties": { "errors": { "additionalProperties": { "type": "string" }, "example": { "first_name": "First name can't be blank" }, "type": "object" } }, "type": "object" } } } }