{ "openapi": "3.1.0", "info": { "title": "ConversionLab core data and reporting API", "version": "current", "description": "ConversionLab core data and reporting API. Authenticate with a team-scoped bearer API key. REST read/write abilities do not override the user role, billing mode, or plan entitlements. The key determines the Team; do not send another team_id. Send Accept: application/json. No API version prefix is used.\n\nThe server URL is an example: replace api.example.test with the API origin supplied for your ConversionLab environment. The /api prefix is part of the existing API. Examples contain fictional data. Uploads use multipart/form-data. JSON requests use Content-Type: application/json. The default API-key rate limit is 120 requests/minute and may be configured by the operator. Honor Retry-After on 429. Validation errors use 422; authentication failures use 401, blocked-billing writes use 402, and permission/entitlement failures use 403. Query options vary by endpoint; use only the listed filters, sorts, and includes." }, "servers": [ { "url": "https://api.example.test/api", "description": "Your API origin (replace this example host)" } ], "paths": { "/activities": { "get": { "operationId": "get_activities", "summary": "List activities", "tags": [ "Activities" ], "parameters": [ { "name": "subject_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "goal", "tag", "experiment", "idea", "insight", "learning", "observation", "page", "audience", "project", "team", "user", "variation", "activity", "comment", "form", "form_question", "form_response", "form_answer", "form_step", "form_response_summary", "project_lookup" ] }, "description": "Subject Type.", "example": "goal" }, { "name": "subject_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Subject Id.", "example": 101 }, { "name": "period", "in": "query", "schema": { "type": "string", "maxLength": 50 }, "description": "Period.", "example": "example" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Per Page.", "example": 1 }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "id", "-id", "created_at", "-created_at", null ] }, "description": "Sort.", "example": "id" } ], "responses": { "200": { "description": "Paginated set of `ActivityResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "log_name": null, "description": "Show the expected delivery date before payment.", "subject_type": null, "subject_id": null, "event": null, "causer_type": null, "causer_id": null, "properties": null, "batch_uuid": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List activities. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/attachments": { "get": { "operationId": "get_attachments", "tags": [ "Attachments" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, created_at, updated_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "name", "created_at", "updated_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[attachable_type]", "in": "query", "description": "Filter by attachable_type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[attachable_id]", "in": "query", "description": "Filter by attachable_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: attachable.", "schema": { "type": "string" }, "x-allowed-values": [ "attachable" ], "example": "example" } ], "responses": { "200": { "description": "Array of `AttachmentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List attachments", "description": "List attachments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_attachments", "tags": [ "Attachments" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreAttachmentRequest" }, "example": { "project_id": 101, "type": "link", "url": "https://example.com/research", "attachable_type": "idea", "attachable_id": 101 } } } }, "responses": { "200": { "description": "`AttachmentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AttachmentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create attachment", "description": "Create attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/attachments/{attachment}": { "delete": { "operationId": "delete_attachments_attachment", "tags": [ "Attachments" ], "parameters": [ { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete attachment", "description": "Delete attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_attachments_attachment", "tags": [ "Attachments" ], "parameters": [ { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`AttachmentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AttachmentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get attachment", "description": "Get attachment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_attachments_attachment", "tags": [ "Attachments" ], "parameters": [ { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAttachmentRequest" }, "example": { "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`AttachmentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AttachmentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update attachment", "description": "Update attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_attachments_attachment", "tags": [ "Attachments" ], "parameters": [ { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAttachmentRequest" }, "example": { "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`AttachmentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AttachmentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update attachment", "description": "Update attachment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/audiences": { "get": { "operationId": "get_audiences", "tags": [ "Audiences" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: project_id, name, created_at, updated_at, experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "project_id", "name", "created_at", "updated_at", "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `AudienceResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List audiences", "description": "List audiences. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_audiences", "tags": [ "Audiences" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAudienceRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "201": { "description": "`AudienceResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AudienceResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create audience", "description": "Create audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/audiences/{audience}": { "delete": { "operationId": "delete_audiences_audience", "tags": [ "Audiences" ], "parameters": [ { "name": "audience", "in": "path", "required": true, "description": "The audience ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete audience", "description": "Delete audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_audiences_audience", "tags": [ "Audiences" ], "parameters": [ { "name": "audience", "in": "path", "required": true, "description": "The audience ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "`AudienceResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AudienceResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get audience", "description": "Get audience. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_audiences_audience", "tags": [ "Audiences" ], "parameters": [ { "name": "audience", "in": "path", "required": true, "description": "The audience ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAudienceRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`AudienceResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AudienceResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update audience", "description": "Update audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_audiences_audience", "tags": [ "Audiences" ], "parameters": [ { "name": "audience", "in": "path", "required": true, "description": "The audience ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAudienceRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`AudienceResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AudienceResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update audience", "description": "Update audience. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/comments": { "get": { "operationId": "get_comments", "summary": "List comments", "tags": [ "Comments" ], "parameters": [ { "name": "commentable_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "insight", "idea", "experiment" ] }, "description": "Commentable Type.", "example": "insight" }, { "name": "commentable_id", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Commentable Id.", "example": 101 }, { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, created_at, updated_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "created_at", "updated_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `CommentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "body": "example", "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List comments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_comments", "summary": "Create comment", "tags": [ "Comments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCommentRequest" }, "example": { "commentable_type": "insight", "commentable_id": 101, "body": "example" } } } }, "responses": { "201": { "description": "`CommentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CommentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "body": "example", "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/comments/{comment}": { "delete": { "operationId": "delete_comments_comment", "summary": "Delete comment", "tags": [ "Comments" ], "parameters": [ { "name": "comment", "in": "path", "required": true, "description": "The comment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "patch": { "operationId": "patch_comments_comment", "summary": "Update comment", "tags": [ "Comments" ], "parameters": [ { "name": "comment", "in": "path", "required": true, "description": "The comment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentRequest" }, "example": { "body": "example" } } } }, "responses": { "200": { "description": "`CommentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CommentResource" }, { "type": "object", "required": [ "user" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "body": "example", "user": null, "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_comments_comment", "summary": "Update comment", "tags": [ "Comments" ], "parameters": [ { "name": "comment", "in": "path", "required": true, "description": "The comment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentRequest" }, "example": { "body": "example" } } } }, "responses": { "200": { "description": "`CommentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CommentResource" }, { "type": "object", "required": [ "user" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "body": "example", "user": null, "user_id": null, "parent_id": null, "is_approved": true, "commentable_type": "example", "commentable_id": 101, "can_edit": true, "can_delete": true, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update comment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/daily-briefs/today": { "get": { "operationId": "get_daily_briefs_today", "tags": [ "Daily Briefs" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "brief_date": { "type": "string" }, "content": { "type": "string" }, "generated_at": { "type": "string" }, "viewed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "brief_date", "content", "generated_at", "viewed_at" ] } }, "required": [ "data" ] }, "example": { "data": null } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get daily brief", "description": "Get daily brief. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. Returns retained content or data: null; this endpoint never generates a brief.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/experiment-states": { "get": { "operationId": "get_experiment_states", "tags": [ "Experiment States" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, name, order.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "name", "order" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[order]", "in": "query", "description": "Filter by order. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `ExperimentStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentStateResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List experiment states", "description": "List experiment states. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_experiment_states", "tags": [ "Experiment States" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreExperimentStateRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "category": "draft" } } } }, "responses": { "200": { "description": "`ExperimentStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create experiment state", "description": "Create experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiment-states/order": { "put": { "operationId": "put_experiment_states_order", "tags": [ "Experiment States" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderExperimentStateRequest" }, "example": { "ids": [ 1 ] } } } }, "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Reorder experiment states", "description": "Reorder experiment states. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiment-states/{experiment_state}": { "delete": { "operationId": "delete_experiment_states_experiment_state", "tags": [ "Experiment States" ], "parameters": [ { "name": "experiment_state", "in": "path", "required": true, "description": "The experiment state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete experiment state", "description": "Delete experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_experiment_states_experiment_state", "tags": [ "Experiment States" ], "parameters": [ { "name": "experiment_state", "in": "path", "required": true, "description": "The experiment state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ExperimentStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get experiment state", "description": "Get experiment state. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_experiment_states_experiment_state", "tags": [ "Experiment States" ], "parameters": [ { "name": "experiment_state", "in": "path", "required": true, "description": "The experiment state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExperimentStateRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ExperimentStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update experiment state", "description": "Update experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_experiment_states_experiment_state", "tags": [ "Experiment States" ], "parameters": [ { "name": "experiment_state", "in": "path", "required": true, "description": "The experiment state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExperimentStateRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ExperimentStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "category": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update experiment state", "description": "Update experiment state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiments": { "get": { "operationId": "get_experiments", "summary": "List experiments", "tags": [ "Experiments" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, type, state_id, custom_id, name, start_date, end_date, user_id.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "type", "state_id", "custom_id", "name", "start_date", "end_date", "user_id" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[type]", "in": "query", "description": "Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[state_id]", "in": "query", "description": "Filter by state_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[custom_id]", "in": "query", "description": "Filter by custom_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: audiences, ideas, insights, metrics, pages, state, variations, user, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "audiences", "ideas", "insights", "metrics", "pages", "state", "variations", "user", "ideasCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `ExperimentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List experiments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_experiments", "summary": "Create experiment", "tags": [ "Experiments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreExperimentRequest" }, "example": { "type": "ab_test", "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`ExperimentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiments/bulk": { "post": { "operationId": "post_experiments_bulk", "summary": "Apply a bulk action to experiments", "tags": [ "Experiments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkExperimentActionRequest" }, "example": { "action": "archive", "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Array of `ExperimentResource`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentResource" } } }, "required": [ "data" ] } ] }, "example": { "action": "delete", "count": 1 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Apply a bulk action to experiments. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiments/{experiment}": { "delete": { "operationId": "delete_experiments_experiment", "summary": "Delete experiment", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_experiments_experiment", "summary": "Get experiment", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: ideas, pages, audiences, insights, metrics, approvals.", "schema": { "type": "string" }, "x-allowed-values": [ "ideas", "pages", "audiences", "insights", "metrics", "approvals" ], "example": "example" } ], "responses": { "200": { "description": "`ExperimentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get experiment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_experiments_experiment", "summary": "Update experiment", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExperimentRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`ExperimentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_experiments_experiment", "summary": "Update experiment", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExperimentRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`ExperimentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiments/{experiment}/approvals": { "get": { "operationId": "get_experiments_experiment_approvals", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Array of `ExperimentApprovalResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentApprovalResource" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 101, "experiment_id": 101, "user_id": 101, "status": "example", "notes": null, "approved_at": "example", "created_at": null } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List experiment approvals", "description": "List experiment approvals. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_experiments_experiment_approvals", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": [ "string", "null" ], "maxLength": 5000 } } }, "example": {} } } }, "responses": { "201": { "description": "`ExperimentApprovalResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentApprovalResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "experiment_id": 101, "user_id": 101, "status": "example", "notes": null, "approved_at": "example", "created_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Record experiment approvals", "description": "Record experiment approvals. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiments/{experiment}/distribute-traffic": { "post": { "operationId": "post_experiments_experiment_distribute_traffic", "summary": "Distribute traffic for experiment", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ExperimentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "type": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "primary_metric_id": null, "start_date": null, "end_date": null, "stop_reason": null, "result": null, "decision": null, "learning": null, "user_id": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Distribute traffic for experiment. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. No request body. Splits the remaining traffic equally among unlocked variations while preserving locked shares. A Live experiment returns 422.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/experiments/{experiment}/summary": { "get": { "operationId": "get_experiments_experiment_summary", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "alpha", "in": "query", "schema": { "type": "string" }, "description": "Alpha.", "example": "example" }, { "name": "srm_alpha", "in": "query", "schema": { "type": "string" }, "description": "Srm Alpha.", "example": "example" } ], "responses": { "200": { "description": "`ExperimentReportResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExperimentReportResource" } }, "required": [ "data" ] }, "example": { "data": { "status": "no_data", "status_reason": "No synced experiment result is available.", "alpha": null, "control_variation_id": null, "method": null, "source": null, "primary_metric": null, "totals": { "visitors": 0, "conversions": 0, "conversion_rate_percent": null }, "srm": null, "variations": [] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get the result report for experiment", "description": "Get the result report for experiment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/experiments/{experiment}/timeseries": { "get": { "operationId": "get_experiments_experiment_timeseries", "summary": "Get result time series for experiment", "tags": [ "Experiments" ], "parameters": [ { "name": "experiment", "in": "path", "required": true, "description": "The experiment ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start.", "example": "2026-01-15T12:00:00Z" }, { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End.", "example": "2026-01-15T12:00:00Z" } ], "responses": { "200": { "description": "Array of `ExperimentTimeseriesResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentTimeseriesResource" } } }, "required": [ "data" ] }, "example": { "data": [ { "variation_id": 101, "name": "Checkout delivery estimate", "points": [ { "date": null, "visitors": 1, "conversions": 1, "conversion_rate": null } ] } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get result time series for experiment. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/forms": { "get": { "operationId": "get_forms", "tags": [ "Forms" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, status, created_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "name", "status", "created_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[status]", "in": "query", "description": "Filter by status. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[type]", "in": "query", "description": "Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `FormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List forms", "description": "List forms. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_forms", "tags": [ "Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFormRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "201": { "description": "`FormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create form", "description": "Create form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/forms/bulk": { "post": { "operationId": "post_forms_bulk", "tags": [ "Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkFormActionRequest" }, "example": { "action": "delete", "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "description": "The bulk action from the request." }, "status": { "type": "string" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "status", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] } ] }, "example": { "action": "example", "status": "example", "count": 1 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Apply a bulk action to forms", "description": "Apply a bulk action to forms. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/forms/duplicate": { "post": { "operationId": "post_forms_duplicate", "tags": [ "Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateFormsRequest" }, "example": { "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Array of `FormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormResource" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "created_at": null, "updated_at": null } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Duplicate form", "description": "Duplicate form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/forms/{form}": { "delete": { "operationId": "delete_forms_form", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete form", "description": "Delete form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_forms_form", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`FormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get form", "description": "Get form. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_forms_form", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFormRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`FormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update form", "description": "Update form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_forms_form", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFormRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`FormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/FormResource" }, { "type": "object", "required": [ "steps" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "public_id": "example-101", "project_id": 101, "name": "Checkout delivery estimate", "description": null, "type": "widget", "status": "draft", "settings": null, "steps": [ { "id": 101, "form_id": 101, "title": null, "description": null, "order": 1, "created_at": null, "updated_at": null } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update form", "description": "Update form. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/forms/{form}/response-summary": { "get": { "operationId": "get_forms_form_response_summary", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "sample_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "description": "Sample Limit.", "example": 1 }, { "name": "theme_limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10 }, "description": "Theme Limit.", "example": 1 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "form_id": { "type": "integer" }, "generated_at": { "type": "string" }, "totals": { "type": "object", "properties": { "responses": { "type": "integer", "minimum": 0 }, "submitted": { "type": "integer", "minimum": 0 }, "partial": { "type": "integer", "minimum": 0 }, "questions": { "type": "integer", "minimum": 0 }, "answers": { "type": "integer", "minimum": 0 }, "completion_rate": { "type": "number" }, "answer_rate": { "type": "number" } }, "required": [ "responses", "submitted", "partial", "questions", "answers", "completion_rate", "answer_rate" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "step_title": { "type": [ "string", "null" ] }, "responses": { "type": "object", "properties": { "answered": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "response_rate": { "type": "number" } }, "required": [ "answered", "skipped", "response_rate" ] }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "percentage": { "type": "number" } }, "required": [ "value", "label", "count", "percentage" ] } }, "metrics": { "anyOf": [ { "type": "object", "properties": { "average": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "nps": { "type": "object", "properties": { "score": { "type": "integer" }, "promoters": { "type": "integer", "minimum": 0 }, "passives": { "type": "integer", "minimum": 0 }, "detractors": { "type": "integer", "minimum": 0 } }, "required": [ "score", "promoters", "passives", "detractors" ] } }, "required": [ "average", "min", "max" ] }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, { "type": "object", "properties": { "emoji": { "type": "object", "properties": { "average_score": { "type": "number" }, "max_score": { "type": "integer" }, "positive": { "type": "integer", "minimum": 0 }, "neutral": { "type": "integer" }, "negative": { "type": "integer", "minimum": 0 }, "scale": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "count": { "type": "integer" }, "percentage": { "type": "number" } }, "required": [ "value", "label", "score", "count", "percentage" ] } }, "top_reaction": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "count": { "type": "integer" }, "percentage": { "type": "number" } }, "required": [ "value", "label", "score", "count", "percentage" ] } }, "required": [ "average_score", "max_score", "positive", "neutral", "negative", "scale", "top_reaction" ] } }, "required": [ "emoji" ] } ] }, "theme_candidates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "integer" }, "examples": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "count", "examples" ] } }, "samples": { "type": "array", "items": { "type": "object", "properties": { "answer_id": { "type": "integer" }, "response_id": { "type": "integer" }, "status": { "type": "string" }, "value": { "type": "string" }, "raw_value": { "type": [ "string", "null" ] }, "page_url": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "answer_id", "response_id", "status", "value", "raw_value", "page_url", "submitted_at", "updated_at" ] } } }, "required": [ "id", "title", "description", "type", "step_title", "responses", "distribution", "metrics", "theme_candidates", "samples" ] } } }, "required": [ "form_id", "generated_at", "totals", "questions" ] } }, "required": [ "data" ] }, "example": { "data": { "form_id": 101, "generated_at": "example", "totals": { "responses": 1, "submitted": 1, "partial": 1, "questions": 1, "answers": 1, "completion_rate": 1, "answer_rate": 1 }, "questions": [ { "id": 101, "title": "Checkout delivery estimate", "description": null, "type": "example", "step_title": null, "responses": { "answered": 1, "skipped": 1, "response_rate": 1 }, "distribution": [ { "value": "example", "label": "example", "count": 1, "percentage": 1 } ], "metrics": { "average": 1, "min": 1, "max": 1 }, "theme_candidates": [ { "label": "example", "count": 1, "examples": [] } ], "samples": [ { "answer_id": 101, "response_id": 101, "status": "example", "value": "example", "raw_value": null, "page_url": null, "submitted_at": null, "updated_at": null } ] } ] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get form", "description": "Get form. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/forms/{form}/responses": { "delete": { "operationId": "delete_forms_form_responses", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Reset survey responses", "description": "Reset survey responses. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. This permanently removes data. Read the request requirements and verify the target before sending.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_forms_form_responses", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, status, submitted_at, created_at, updated_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "status", "submitted_at", "created_at", "updated_at" ], "example": "example" }, { "name": "filter[status]", "in": "query", "description": "Filter by status. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `FormResponseResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormResponseResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "form_id": 101, "response_key": null, "respondent_id": null, "status": "example", "page_url": null, "user_agent": null, "referrer": null, "language": null, "timezone": null, "viewport_width": null, "viewport_height": null, "screen_width": null, "screen_height": null, "client_type": null, "browser_name": null, "browser_version": null, "os_name": null, "os_version": null, "device_type": null, "is_bot": true, "submitted_at": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List forms", "description": "List forms. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/forms/{form}/responses/export": { "get": { "operationId": "get_forms_form_responses_export", "tags": [ "Forms" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "description": "Format.", "example": "csv" }, { "name": "filter[status]", "in": "query", "schema": { "anyOf": [ { "$ref": "#/components/schemas/FormResponseStatus" }, { "type": "null" } ] }, "description": "Filter[Status].", "example": null } ], "responses": { "200": { "description": "Successful response.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } }, "text/csv; charset=UTF-8": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Export responses for form", "description": "Export responses for form. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/idea-states": { "get": { "operationId": "get_idea_states", "tags": [ "Idea States" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, name, order.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "name", "order" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[order]", "in": "query", "description": "Filter by order. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `IdeaStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IdeaStateResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List idea states", "description": "List idea states. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_idea_states", "tags": [ "Idea States" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreIdeaStateRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "color": "#3b82f6" } } } }, "responses": { "200": { "description": "`IdeaStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create idea state", "description": "Create idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/idea-states/order": { "put": { "operationId": "put_idea_states_order", "tags": [ "Idea States" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderIdeaStateRequest" }, "example": { "ids": [ 1 ] } } } }, "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Reorder idea states", "description": "Reorder idea states. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/idea-states/{idea_state}": { "delete": { "operationId": "delete_idea_states_idea_state", "tags": [ "Idea States" ], "parameters": [ { "name": "idea_state", "in": "path", "required": true, "description": "The idea state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0, "description": "Empty JSON object returned after deletion." }, "example": {} } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete idea state", "description": "Delete idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_idea_states_idea_state", "tags": [ "Idea States" ], "parameters": [ { "name": "idea_state", "in": "path", "required": true, "description": "The idea state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`IdeaStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get idea state", "description": "Get idea state. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_idea_states_idea_state", "tags": [ "Idea States" ], "parameters": [ { "name": "idea_state", "in": "path", "required": true, "description": "The idea state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdeaStateRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`IdeaStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update idea state", "description": "Update idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_idea_states_idea_state", "tags": [ "Idea States" ], "parameters": [ { "name": "idea_state", "in": "path", "required": true, "description": "The idea state ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdeaStateRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`IdeaStateResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaStateResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "description": null, "color": null, "order": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update idea state", "description": "Update idea state. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/ideas": { "get": { "operationId": "get_ideas", "summary": "List ideas", "tags": [ "Ideas" ], "parameters": [ { "name": "include[]", "in": "query", "schema": { "type": "array", "enum": [ "audiences", "experiments", "insights", "metrics", "pages", "state", "ideasCount", "experimentsCount", "insightsCount" ], "items": { "type": "string", "enum": [ "audiences", "experiments", "insights", "metrics", "pages", "state", "ideasCount", "experimentsCount", "insightsCount" ] } }, "description": "Include[].", "example": "audiences" }, { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, state_id, custom_id, name, priority_score.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "state_id", "custom_id", "name", "priority_score" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[state_id]", "in": "query", "description": "Filter by state_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[custom_id]", "in": "query", "description": "Filter by custom_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: audiences, experiments, insights, metrics, pages, state, experimentsCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "audiences", "experiments", "insights", "metrics", "pages", "state", "experimentsCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `IdeaResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IdeaResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List ideas. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_ideas", "summary": "Create idea", "tags": [ "Ideas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreIdeaRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`IdeaResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/ideas/bulk": { "post": { "operationId": "post_ideas_bulk", "summary": "Apply a bulk action to ideas", "tags": [ "Ideas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkIdeaActionRequest" }, "example": { "action": "archive", "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Array of `IdeaResource`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IdeaResource" } } }, "required": [ "data" ] } ] }, "example": { "action": "delete", "count": 1 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Apply a bulk action to ideas. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/ideas/{idea}": { "delete": { "operationId": "delete_ideas_idea", "summary": "Delete idea", "tags": [ "Ideas" ], "parameters": [ { "name": "idea", "in": "path", "required": true, "description": "The idea ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Idea deleted successfully" } }, "required": [ "message" ] }, "example": { "message": "Idea deleted successfully" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_ideas_idea", "summary": "Get idea", "tags": [ "Ideas" ], "parameters": [ { "name": "idea", "in": "path", "required": true, "description": "The idea ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: audiences, experiments, insights, metrics, pages.", "schema": { "type": "string" }, "x-allowed-values": [ "audiences", "experiments", "insights", "metrics", "pages" ], "example": "example" } ], "responses": { "200": { "description": "`IdeaResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/IdeaResource" }, { "type": "object", "required": [ "audiences" ] } ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null, "audiences": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get idea. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_ideas_idea", "summary": "Update idea", "tags": [ "Ideas" ], "parameters": [ { "name": "idea", "in": "path", "required": true, "description": "The idea ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdeaRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`IdeaResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_ideas_idea", "summary": "Update idea", "tags": [ "Ideas" ], "parameters": [ { "name": "idea", "in": "path", "required": true, "description": "The idea ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdeaRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`IdeaResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdeaResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "project_id": null, "state_id": null, "name": "Checkout delivery estimate", "description": null, "hypothesis": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_name": null, "priority_values": null, "priority_score": null, "priority_details": null, "priority_calculated_at": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update idea. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/insight-labels": { "get": { "operationId": "get_insight_labels", "tags": [ "Insight Labels" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: project_id, name, created_at, updated_at, insightsCount, screenAnnotationsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "project_id", "name", "created_at", "updated_at", "insightsCount", "screenAnnotationsCount" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: insightsCount, screenAnnotationsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "insightsCount", "screenAnnotationsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `InsightLabelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightLabelResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List insight labels", "description": "List insight labels. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_insight_labels", "tags": [ "Insight Labels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInsightLabelRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "color": "gray" } } } }, "responses": { "200": { "description": "`InsightLabelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightLabelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create insight label", "description": "Create insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/insight-labels/{insight_label}": { "delete": { "operationId": "delete_insight_labels_insight_label", "tags": [ "Insight Labels" ], "parameters": [ { "name": "insight_label", "in": "path", "required": true, "description": "The insight label ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete insight label", "description": "Delete insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_insight_labels_insight_label", "tags": [ "Insight Labels" ], "parameters": [ { "name": "insight_label", "in": "path", "required": true, "description": "The insight label ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`InsightLabelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightLabelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get insight label", "description": "Get insight label. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_insight_labels_insight_label", "tags": [ "Insight Labels" ], "parameters": [ { "name": "insight_label", "in": "path", "required": true, "description": "The insight label ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInsightLabelRequest" }, "example": { "project_id": 101, "name": null } } } }, "responses": { "200": { "description": "`InsightLabelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightLabelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update insight label", "description": "Update insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_insight_labels_insight_label", "tags": [ "Insight Labels" ], "parameters": [ { "name": "insight_label", "in": "path", "required": true, "description": "The insight label ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInsightLabelRequest" }, "example": { "project_id": 101, "name": null } } } }, "responses": { "200": { "description": "`InsightLabelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightLabelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": null, "name": null, "color": null, "order": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update insight label", "description": "Update insight label. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/insights": { "get": { "operationId": "get_insights", "summary": "List insights", "tags": [ "Insights" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, research_collection_id, user_id, custom_id, name, source.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "research_collection_id", "user_id", "custom_id", "name", "source" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[research_collection_id]", "in": "query", "description": "Filter by research_collection_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[custom_id]", "in": "query", "description": "Filter by custom_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[source]", "in": "query", "description": "Filter by source. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: audiences, experiments, ideas, learnings, observations, pages, screenAnnotations, ideasCount, experimentsCount, learningsCount, observationsCount, screenAnnotationsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "audiences", "experiments", "ideas", "learnings", "observations", "pages", "screenAnnotations", "ideasCount", "experimentsCount", "learningsCount", "observationsCount", "screenAnnotationsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `InsightResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List insights. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_insights", "summary": "Create insight", "tags": [ "Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInsightRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`InsightResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/insights/bulk": { "post": { "operationId": "post_insights_bulk", "summary": "Apply a bulk action to insights", "tags": [ "Insights" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInsightActionRequest" }, "example": { "action": "archive", "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Array of `InsightResource`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InsightResource" } } }, "required": [ "data" ] } ] }, "example": { "action": "delete", "count": 1 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Apply a bulk action to insights. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/insights/{insight}": { "delete": { "operationId": "delete_insights_insight", "summary": "Delete insight", "tags": [ "Insights" ], "parameters": [ { "name": "insight", "in": "path", "required": true, "description": "The insight ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_insights_insight", "summary": "Get insight", "tags": [ "Insights" ], "parameters": [ { "name": "insight", "in": "path", "required": true, "description": "The insight ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: ideasCount, experimentsCount, learningsCount, observationsCount, screenAnnotationsCount, audiences, experiments, ideas, learnings, observations, pages, screenAnnotations.", "schema": { "type": "string" }, "x-allowed-values": [ "ideasCount", "experimentsCount", "learningsCount", "observationsCount", "screenAnnotationsCount", "audiences", "experiments", "ideas", "learnings", "observations", "pages", "screenAnnotations" ], "example": "example" } ], "responses": { "200": { "description": "`InsightResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get insight. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_insights_insight", "summary": "Update insight", "tags": [ "Insights" ], "parameters": [ { "name": "insight", "in": "path", "required": true, "description": "The insight ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInsightRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`InsightResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_insights_insight", "summary": "Update insight", "tags": [ "Insights" ], "parameters": [ { "name": "insight", "in": "path", "required": true, "description": "The insight ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInsightRequest" }, "example": { "name": "Checkout delivery estimate", "description": null, "project_id": 101 } } } }, "responses": { "200": { "description": "`InsightResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "custom_id": null, "numbering_scheme_id": null, "custom_id_number": null, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "research_collection_id": null, "insight_label_id": null, "user_id": null, "source": null, "source_id": null, "source_item_key": null, "source_label": null, "name": null, "description": null, "created_at": null, "updated_at": null, "deleted_at": null, "has_ideas": true } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update insight. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/learnings": { "get": { "operationId": "get_learnings", "tags": [ "Learnings" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, research_collection_id, user_id, name, confidence, learned_at, created_at, updated_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "research_collection_id", "user_id", "name", "confidence", "learned_at", "created_at", "updated_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[research_collection_id]", "in": "query", "description": "Filter by research_collection_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[confidence]", "in": "query", "description": "Filter by confidence. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: insights, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "insights", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `LearningResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LearningResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List learnings", "description": "List learnings. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_learnings", "tags": [ "Learnings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreLearningRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`LearningResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LearningResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create learning", "description": "Create learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/learnings/bulk": { "post": { "operationId": "post_learnings_bulk", "tags": [ "Learnings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLearningActionRequest" }, "example": { "action": "archive", "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Array of `LearningResource`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LearningResource" } } }, "required": [ "data" ] } ] }, "example": { "action": "delete", "count": 1 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Apply a bulk action to learnings", "description": "Apply a bulk action to learnings. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/learnings/{learning}": { "delete": { "operationId": "delete_learnings_learning", "tags": [ "Learnings" ], "parameters": [ { "name": "learning", "in": "path", "required": true, "description": "The learning ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete learning", "description": "Delete learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_learnings_learning", "tags": [ "Learnings" ], "parameters": [ { "name": "learning", "in": "path", "required": true, "description": "The learning ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: insightsCount, insights.", "schema": { "type": "string" }, "x-allowed-values": [ "insightsCount", "insights" ], "example": "example" } ], "responses": { "200": { "description": "`LearningResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LearningResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get learning", "description": "Get learning. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_learnings_learning", "tags": [ "Learnings" ], "parameters": [ { "name": "learning", "in": "path", "required": true, "description": "The learning ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLearningRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`LearningResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LearningResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update learning", "description": "Update learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_learnings_learning", "tags": [ "Learnings" ], "parameters": [ { "name": "learning", "in": "path", "required": true, "description": "The learning ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLearningRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`LearningResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LearningResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "confidence": null, "learned_at": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update learning", "description": "Update learning. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/metrics": { "get": { "operationId": "get_metrics", "summary": "List metrics", "tags": [ "Metrics" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, winning_direction, type, project_id.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "name", "winning_direction", "type", "project_id" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[winning_direction]", "in": "query", "description": "Filter by winning_direction. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[type]", "in": "query", "description": "Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `MetricResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List metrics. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_metrics", "summary": "Create metric", "tags": [ "Metrics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreMetricRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "winning_direction": "increasing", "type": "average-per-user" } } } }, "responses": { "201": { "description": "`MetricResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/metrics/{metric}": { "delete": { "operationId": "delete_metrics_metric", "summary": "Delete metric", "tags": [ "Metrics" ], "parameters": [ { "name": "metric", "in": "path", "required": true, "description": "The metric ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_metrics_metric", "summary": "Get metric", "tags": [ "Metrics" ], "parameters": [ { "name": "metric", "in": "path", "required": true, "description": "The metric ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`MetricResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get metric. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_metrics_metric", "summary": "Update metric", "tags": [ "Metrics" ], "parameters": [ { "name": "metric", "in": "path", "required": true, "description": "The metric ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`MetricResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_metrics_metric", "summary": "Update metric", "tags": [ "Metrics" ], "parameters": [ { "name": "metric", "in": "path", "required": true, "description": "The metric ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`MetricResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MetricResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "description": null, "type": null, "winning_direction": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update metric. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/numbering-schemes": { "get": { "operationId": "get_numbering_schemes", "tags": [ "Numbering Schemes" ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List numbering schemes", "description": "List numbering schemes. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_numbering_schemes", "tags": [ "Numbering Schemes" ], "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "scope": { "type": "string", "enum": [ "team", "project" ] }, "template": { "type": "string", "maxLength": 120, "description": "Identifier template, for example EXP-{number:000}. Project-scoped templates may include {project_code}." }, "initial_number": { "type": "integer", "minimum": 1 }, "is_active": { "type": "boolean" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "entity_type" ] } } }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] }, "required": [ "name", "scope", "template" ] }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } } } }, "summary": "Create numbering scheme", "description": "Create numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/numbering-schemes/preview": { "post": { "operationId": "post_numbering_schemes_preview", "tags": [ "Numbering Schemes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "maxLength": 120 }, "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] }, "next_number": { "type": "integer", "minimum": 1 }, "project_code": { "type": [ "string", "null" ], "maxLength": 24 } }, "required": [ "template", "entity_type" ] }, "example": { "template": "example", "entity_type": "experiments", "project_id": null } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" }, { "type": "string" } ], "minItems": 3, "maxItems": 3 } }, "required": [ "data" ] }, "example": { "data": [ "example", "example", "example" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Preview numbering scheme", "description": "Preview numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/numbering-schemes/{numberingScheme}": { "patch": { "operationId": "patch_numbering_schemes_numberingScheme", "tags": [ "Numbering Schemes" ], "parameters": [ { "name": "numberingScheme", "in": "path", "required": true, "description": "The numbering scheme ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSchemeInput" }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } } } }, "summary": "Update numbering scheme", "description": "Update numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_numbering_schemes_numberingScheme", "tags": [ "Numbering Schemes" ], "parameters": [ { "name": "numberingScheme", "in": "path", "required": true, "description": "The numbering scheme ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberingSchemeInput" }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } } } }, "summary": "Update numbering scheme", "description": "Update numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/numbering-schemes/{numberingScheme}/backfill": { "post": { "operationId": "post_numbering_schemes_numberingScheme_backfill", "tags": [ "Numbering Schemes" ], "parameters": [ { "name": "numberingScheme", "in": "path", "required": true, "description": "The numbering scheme ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "backfilled": { "type": "integer" }, "scheme": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string" }, "template": { "type": "string" }, "initial_number": { "type": "integer" }, "is_active": { "type": "boolean" }, "claims_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "entity_type": { "type": "string" }, "assignment_scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "entity_type", "assignment_scope_key", "project_id" ] } }, "sequence_states": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "scope_key": { "type": "string" }, "project_id": { "type": [ "integer", "null" ] }, "project_code": { "type": [ "string", "null" ] }, "next_number": { "type": "integer" } }, "required": [ "id", "scope_key", "project_id", "project_code", "next_number" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "scope", "template", "initial_number", "is_active", "claims_count", "assignments", "sequence_states", "created_at", "updated_at" ] } }, "required": [ "backfilled", "scheme" ] } }, "required": [ "data" ] }, "example": { "data": { "backfilled": 1, "scheme": { "id": 101, "name": "Checkout delivery estimate", "scope": "example", "template": "example", "initial_number": 1, "is_active": true, "claims_count": "example", "assignments": [ { "id": 101, "entity_type": "example", "assignment_scope_key": "example", "project_id": null } ], "sequence_states": [ { "id": 101, "scope_key": "example", "project_id": null, "project_code": null, "next_number": 1 } ], "created_at": null, "updated_at": null } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Backfill identifiers using numbering scheme", "description": "Backfill identifiers using numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations": { "get": { "operationId": "get_observations", "tags": [ "Observations" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, research_collection_id, user_id, name, source_type, evidence_kind, confidence, observed_at, created_at, updated_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "research_collection_id", "user_id", "name", "source_type", "evidence_kind", "confidence", "observed_at", "created_at", "updated_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[research_collection_id]", "in": "query", "description": "Filter by research_collection_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[source_type]", "in": "query", "description": "Filter by source_type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[source_id]", "in": "query", "description": "Filter by source_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[evidence_kind]", "in": "query", "description": "Filter by evidence_kind. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[confidence]", "in": "query", "description": "Filter by confidence. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[locked]", "in": "query", "description": "Filter by locked. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[review_status]", "in": "query", "description": "Filter by review_status. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[source_label]", "in": "query", "description": "Filter by source_label. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: insights, pages, screenAnnotations, insightsCount, pagesCount, screenAnnotationsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "insights", "pages", "screenAnnotations", "insightsCount", "pagesCount", "screenAnnotationsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ObservationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List observations", "description": "List observations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_observations", "tags": [ "Observations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreObservationRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create observation", "description": "Create observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/bulk": { "post": { "operationId": "post_observations_bulk", "tags": [ "Observations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkObservationActionRequest" }, "example": { "action": "accept", "ids": [ 1 ] } } } }, "responses": { "200": { "description": "Array of `ObservationResource`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "const": "archive" }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "action": { "type": "string", "description": "The bulk action from the request." }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "action", "count" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ObservationResource" } } }, "required": [ "data" ] } ] }, "example": { "action": "delete", "count": 1 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Apply a bulk action to observations", "description": "Apply a bulk action to observations. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/{observation}": { "delete": { "operationId": "delete_observations_observation", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete observation", "description": "Delete observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_observations_observation", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: insightsCount, screenAnnotationsCount, pagesCount, insights, screenAnnotations, pages.", "schema": { "type": "string" }, "x-allowed-values": [ "insightsCount", "screenAnnotationsCount", "pagesCount", "insights", "screenAnnotations", "pages" ], "example": "example" } ], "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get observation", "description": "Get observation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_observations_observation", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateObservationRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update observation", "description": "Update observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_observations_observation", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateObservationRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update observation", "description": "Update observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/{observation}/accept": { "post": { "operationId": "post_observations_observation_accept", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Accept observation", "description": "Accept observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/{observation}/dismiss": { "post": { "operationId": "post_observations_observation_dismiss", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Dismiss observation", "description": "Dismiss observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/{observation}/force": { "delete": { "operationId": "delete_observations_observation_force", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Observation.", "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Permanently delete an archived observation", "description": "Permanently delete an archived observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. This permanently removes data. Read the request requirements and verify the target before sending.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/{observation}/restore": { "post": { "operationId": "post_observations_observation_restore", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Observation.", "example": 1 } ], "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Restore an archived observation", "description": "Restore an archived observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/observations/{observation}/restore-dismissal": { "post": { "operationId": "post_observations_observation_restore_dismissal", "tags": [ "Observations" ], "parameters": [ { "name": "observation", "in": "path", "required": true, "description": "The observation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ObservationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ObservationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "user_id": null, "name": "Checkout delivery estimate", "description": null, "source_type": "example", "source_id": null, "source_item_key": null, "source_label": null, "evidence_kind": null, "evidence_payload": null, "confidence": null, "observed_at": null, "locked": true, "accepted_at": null, "accepted_by": null, "dismissed_at": null, "dismissed_by": null, "created_at": null, "updated_at": null, "deleted_at": null, "review_status": "example" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Restore a dismissed observation", "description": "Restore a dismissed observation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/pages": { "get": { "operationId": "get_pages", "tags": [ "Pages" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: project_id, name, created_at, updated_at, experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "project_id", "name", "created_at", "updated_at", "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `PageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PageResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List pages", "description": "List pages. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_pages", "tags": [ "Pages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePageRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "201": { "description": "`PageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create page", "description": "Create page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/pages/{page}": { "delete": { "operationId": "delete_pages_page", "tags": [ "Pages" ], "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The page ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete page", "description": "Delete page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_pages_page", "tags": [ "Pages" ], "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The page ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "`PageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get page", "description": "Get page. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_pages_page", "tags": [ "Pages" ], "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The page ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePageRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`PageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update page", "description": "Update page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_pages_page", "tags": [ "Pages" ], "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The page ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePageRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`PageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "name": "Checkout delivery estimate", "description": null, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update page", "description": "Update page. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/prio-models": { "get": { "operationId": "get_prio_models", "summary": "List prio models", "tags": [ "Prio Models" ], "parameters": [ { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: name.", "schema": { "type": "string" }, "x-allowed-values": [ "name" ], "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `PrioModelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrioModelResource" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List prio models. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_prio_models", "summary": "Create prio model", "tags": [ "Prio Models" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePrioModelRequest" }, "example": { "name": "ICE", "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } } } } }, "responses": { "201": { "description": "`PrioModelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrioModelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/prio-models/validate-formula": { "post": { "operationId": "post_prio_models_validate_formula", "summary": "Validate the formula for prio model", "tags": [ "Prio Models" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatePrioModelFormulaRequest" }, "example": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "message": { "type": "string", "const": "Formula is valid" }, "sample_result": { "$ref": "#/components/schemas/JsonValue" }, "sample_values": { "type": "object", "additionalProperties": { "type": [ "number", "boolean" ] } } }, "required": [ "valid", "message", "sample_result", "sample_values" ], "example": { "valid": true, "message": "Formula is valid", "sample_result": 5, "sample_values": { "impact": 5, "confidence": 5, "effort": 5 } } }, "example": { "valid": true, "message": "Formula is valid", "sample_result": 5, "sample_values": { "impact": 5, "confidence": 5, "effort": 5 } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation failed or the expression cannot be evaluated.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "valid": { "type": "boolean", "const": false }, "message": { "type": "string" }, "sample_values": { "type": "object", "additionalProperties": { "type": [ "number", "boolean" ] } } }, "required": [ "valid", "message", "sample_values" ] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } ] }, "example": { "valid": false, "message": "The request could not be completed.", "sample_values": {} } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Validate the formula for prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/prio-models/{id}/recalculate": { "post": { "operationId": "post_prio_models_id_recalculate", "summary": "Recalculate priorities with prio model", "tags": [ "Prio Models" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Id.", "example": 101 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecalculatePrioModelRequest" }, "example": { "project_id": 101, "id": 101 } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Priorities recalculated successfully" } }, "required": [ "message" ] }, "example": { "message": "Priorities recalculated successfully" } } } }, "400": { "description": "The request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No prioritization configuration found for this project" } }, "required": [ "message" ] }, "example": { "message": "No prioritization configuration found for this project" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Recalculate priorities with prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/prio-models/{prio_model}": { "delete": { "operationId": "delete_prio_models_prio_model", "summary": "Delete prio model", "tags": [ "Prio Models" ], "parameters": [ { "name": "prio_model", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Prio Model.", "example": 1 }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Project Id.", "example": 101 }, { "name": "id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Id.", "example": 101 } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Prioritization model removed successfully" } }, "required": [ "message" ] }, "example": { "message": "Prioritization model removed successfully" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_prio_models_prio_model", "summary": "Get prio model", "tags": [ "Prio Models" ], "parameters": [ { "name": "prio_model", "in": "path", "required": true, "description": "The prio model ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`PrioModelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrioModelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get prio model. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_prio_models_prio_model", "summary": "Update prio model", "tags": [ "Prio Models" ], "parameters": [ { "name": "prio_model", "in": "path", "required": true, "description": "The prio model ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdatePrioModelRequest" }, { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "string" } } } ] }, "example": { "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] } } } } }, "responses": { "200": { "description": "`PrioModelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrioModelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_prio_models_prio_model", "summary": "Update prio model", "tags": [ "Prio Models" ], "parameters": [ { "name": "prio_model", "in": "path", "required": true, "description": "The prio model ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdatePrioModelRequest" }, { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "string" } } } ] }, "example": { "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] } } } } }, "responses": { "200": { "description": "`PrioModelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrioModelResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "name": "Checkout delivery estimate", "description": null, "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Checkout delivery estimate", "key": "example", "description": null, "type": "number" } ] }, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update prio model. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/projects": { "get": { "operationId": "get_projects", "summary": "List projects", "tags": [ "Projects" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, state, name.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "state", "name" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[state]", "in": "query", "description": "Filter by state. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List projects. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_projects", "summary": "Create project", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreProjectRequest" }, "example": { "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/projects/{project}": { "delete": { "operationId": "delete_projects_project", "summary": "Delete project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The project ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_projects_project", "summary": "Get project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The project ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Include the project prioritization model with include=prio_model.", "schema": { "type": "string", "enum": [ "prio_model" ] }, "example": "prio_model" } ], "responses": { "200": { "description": "`ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get project. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_projects_project", "summary": "Update project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The project ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" }, "example": { "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "post": { "operationId": "post_projects_project", "summary": "Update project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The project ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" }, "example": { "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_projects_project", "summary": "Update project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The project ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" }, "example": { "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "public_id": "example-101", "state": null, "name": "Checkout delivery estimate", "cover": null, "color": null, "prio_model_id": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update project. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/research-collections": { "get": { "operationId": "get_research_collections", "tags": [ "Research Collections" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, name, created_at, updated_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "name", "created_at", "updated_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `ResearchCollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResearchCollectionResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List research collections", "description": "List research collections. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_research_collections", "tags": [ "Research Collections" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreResearchCollectionRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ResearchCollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResearchCollectionResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "The request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] }, "example": { "error": "Error uploading file" } } } } }, "summary": "Create research collection", "description": "Create research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/research-collections/{research_collection}": { "delete": { "operationId": "delete_research_collections_research_collection", "tags": [ "Research Collections" ], "parameters": [ { "name": "research_collection", "in": "path", "required": true, "description": "The research collection ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete research collection", "description": "Delete research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_research_collections_research_collection", "tags": [ "Research Collections" ], "parameters": [ { "name": "research_collection", "in": "path", "required": true, "description": "The research collection ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ResearchCollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResearchCollectionResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get research collection", "description": "Get research collection. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_research_collections_research_collection", "tags": [ "Research Collections" ], "parameters": [ { "name": "research_collection", "in": "path", "required": true, "description": "The research collection ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateResearchCollectionRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ResearchCollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResearchCollectionResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "The request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] }, "example": { "error": "Error uploading file" } } } } }, "summary": "Update research collection", "description": "Update research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "post": { "operationId": "post_research_collections_research_collection", "tags": [ "Research Collections" ], "parameters": [ { "name": "research_collection", "in": "path", "required": true, "description": "The research collection ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateResearchCollectionRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ResearchCollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResearchCollectionResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "The request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] }, "example": { "error": "Error uploading file" } } } } }, "summary": "Update research collection", "description": "Update research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_research_collections_research_collection", "tags": [ "Research Collections" ], "parameters": [ { "name": "research_collection", "in": "path", "required": true, "description": "The research collection ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UpdateResearchCollectionRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ResearchCollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResearchCollectionResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "name": null, "description": null, "cover": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "The request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] }, "example": { "error": "Error uploading file" } } } } }, "summary": "Update research collection", "description": "Update research collection. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/roadmap-annotations": { "get": { "operationId": "get_roadmap_annotations", "tags": [ "Roadmap Annotations" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, type, annotation_type, label, start_date, end_date, created_at.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "created_at" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[type]", "in": "query", "description": "Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[annotation_type]", "in": "query", "description": "Filter by annotation_type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[label]", "in": "query", "description": "Filter by label. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `RoadmapAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoadmapAnnotationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List roadmap annotations", "description": "List roadmap annotations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_roadmap_annotations", "tags": [ "Roadmap Annotations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreRoadmapAnnotationRequest" }, "example": { "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z" } } } }, "responses": { "200": { "description": "`RoadmapAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoadmapAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create roadmap annotation", "description": "Create roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/roadmap-annotations/{roadmap_annotation}": { "delete": { "operationId": "delete_roadmap_annotations_roadmap_annotation", "tags": [ "Roadmap Annotations" ], "parameters": [ { "name": "roadmap_annotation", "in": "path", "required": true, "description": "The roadmap annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete roadmap annotation", "description": "Delete roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_roadmap_annotations_roadmap_annotation", "tags": [ "Roadmap Annotations" ], "parameters": [ { "name": "roadmap_annotation", "in": "path", "required": true, "description": "The roadmap annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`RoadmapAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoadmapAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get roadmap annotation", "description": "Get roadmap annotation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_roadmap_annotations_roadmap_annotation", "tags": [ "Roadmap Annotations" ], "parameters": [ { "name": "roadmap_annotation", "in": "path", "required": true, "description": "The roadmap annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoadmapAnnotationRequest" }, "example": { "project_id": 101 } } } }, "responses": { "200": { "description": "`RoadmapAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoadmapAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update roadmap annotation", "description": "Update roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_roadmap_annotations_roadmap_annotation", "tags": [ "Roadmap Annotations" ], "parameters": [ { "name": "roadmap_annotation", "in": "path", "required": true, "description": "The roadmap annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoadmapAnnotationRequest" }, "example": { "project_id": 101 } } } }, "responses": { "200": { "description": "`RoadmapAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoadmapAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "type": "overlay", "annotation_type": "example", "label": "example", "start_date": "2026-01-15T12:00:00Z", "end_date": null, "notes": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update roadmap annotation", "description": "Update roadmap annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/screen-annotations": { "get": { "operationId": "get_screen_annotations", "tags": [ "Screen Annotations" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, screen_id, note, x, y, width, height, shape, user_id.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "screen_id", "note", "x", "y", "width", "height", "shape", "user_id" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[screen_id]", "in": "query", "description": "Filter by screen_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[note]", "in": "query", "description": "Filter by note. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[x]", "in": "query", "description": "Filter by x. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[y]", "in": "query", "description": "Filter by y. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[shape]", "in": "query", "description": "Filter by shape. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[user_id]", "in": "query", "description": "Filter by user_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `ScreenAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScreenAnnotationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List screen annotations", "description": "List screen annotations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_screen_annotations", "tags": [ "Screen Annotations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreScreenAnnotationsRequest" }, "example": { "project_id": 101, "screen_id": 101, "x": 1, "y": 1 } } } }, "responses": { "200": { "description": "`ScreenAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create screen annotation", "description": "Create screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/screen-annotations/{screen_annotation}": { "delete": { "operationId": "delete_screen_annotations_screen_annotation", "tags": [ "Screen Annotations" ], "parameters": [ { "name": "screen_annotation", "in": "path", "required": true, "description": "The screen annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete screen annotation", "description": "Delete screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_screen_annotations_screen_annotation", "tags": [ "Screen Annotations" ], "parameters": [ { "name": "screen_annotation", "in": "path", "required": true, "description": "The screen annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`ScreenAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get screen annotation", "description": "Get screen annotation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_screen_annotations_screen_annotation", "tags": [ "Screen Annotations" ], "parameters": [ { "name": "screen_annotation", "in": "path", "required": true, "description": "The screen annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScreenAnnotationRequest" }, "example": { "project_id": 101 } } } }, "responses": { "200": { "description": "`ScreenAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update screen annotation", "description": "Update screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_screen_annotations_screen_annotation", "tags": [ "Screen Annotations" ], "parameters": [ { "name": "screen_annotation", "in": "path", "required": true, "description": "The screen annotation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScreenAnnotationRequest" }, "example": { "project_id": 101 } } } }, "responses": { "200": { "description": "`ScreenAnnotationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenAnnotationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "screen_id": 101, "insight_label_id": null, "note": null, "x": null, "y": null, "width": null, "height": null, "shape": "example", "metadata": null, "user_id": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update screen annotation", "description": "Update screen annotation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/screens": { "get": { "operationId": "get_screens", "tags": [ "Screens" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, project_id, research_collection_id, audience_id, page_id, name, description.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[research_collection_id]", "in": "query", "description": "Filter by research_collection_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[audience_id]", "in": "query", "description": "Filter by audience_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[page_id]", "in": "query", "description": "Filter by page_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[description]", "in": "query", "description": "Filter by description. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `ScreenResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScreenResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List screens", "description": "List screens. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_screens", "tags": [ "Screens" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreScreenRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null, "image": "screenshot.png" } } } }, "responses": { "200": { "description": "`ScreenResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "The request failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Error uploading file" } }, "required": [ "error" ] }, "example": { "error": "Error uploading file" } } } } }, "summary": "Create screen", "description": "Create screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/screens/{screen}": { "delete": { "operationId": "delete_screens_screen", "tags": [ "Screens" ], "parameters": [ { "name": "screen", "in": "path", "required": true, "description": "The screen ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete screen", "description": "Delete screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_screens_screen", "tags": [ "Screens" ], "parameters": [ { "name": "screen", "in": "path", "required": true, "description": "The screen ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "include", "in": "query", "description": "Comma-separated relationships or counts. Allowed: audience, page, insights, annotations.", "schema": { "type": "string" }, "x-allowed-values": [ "audience", "page", "insights", "annotations" ], "example": "example" } ], "responses": { "200": { "description": "`ScreenResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get screen", "description": "Get screen. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_screens_screen", "tags": [ "Screens" ], "parameters": [ { "name": "screen", "in": "path", "required": true, "description": "The screen ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScreenRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ScreenResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update screen", "description": "Update screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_screens_screen", "tags": [ "Screens" ], "parameters": [ { "name": "screen", "in": "path", "required": true, "description": "The screen ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScreenRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`ScreenResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "project_id": 101, "research_collection_id": null, "audience_id": null, "page_id": null, "name": null, "description": null, "image": null, "width": null, "height": null, "created_at": null, "updated_at": null, "deleted_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update screen", "description": "Update screen. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/tags": { "get": { "operationId": "get_tags", "summary": "List tags", "tags": [ "Tags" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: id, name, type.", "schema": { "type": "string" }, "x-allowed-values": [ "id", "name", "type" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[type]", "in": "query", "description": "Filter by type. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "include", "in": "query", "description": "Comma-separated relationships. Allowed: experimentsCount, ideasCount, insightsCount.", "schema": { "type": "string" }, "x-allowed-values": [ "experimentsCount", "ideasCount", "insightsCount" ], "example": "example" } ], "responses": { "200": { "description": "Array of `TagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TagResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "List tags. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_tags", "summary": "Create tag", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreTagRequest" }, "example": { "project_id": 101, "name": "Checkout delivery estimate", "type": "generic", "description": null } } } }, "responses": { "201": { "description": "`TagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TagResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Create tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/tags/{tag}": { "delete": { "operationId": "delete_tags_tag", "summary": "Delete tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "description": "The tag ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Delete tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_tags_tag", "summary": "Get tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "description": "The tag ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`TagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TagResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Get tag. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_tags_tag", "summary": "Update tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "description": "The tag ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`TagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TagResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_tags_tag", "summary": "Update tag", "tags": [ "Tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "description": "The tag ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" }, "example": { "name": "Checkout delivery estimate", "description": null } } } }, "responses": { "200": { "description": "`TagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TagResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": null, "name": "Checkout delivery estimate", "type": "generic", "description": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "description": "Update tag. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/user": { "get": { "responses": { "200": { "description": "`User`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": 101, "name": "Checkout delivery estimate", "avatar": null, "email": "alex@example.com", "timezone": null, "email_verified_at": null, "last_login_at": null, "last_visited_team_id": null, "created_at": null, "updated_at": null } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get the authenticated user", "operationId": "get_user", "tags": [ "User" ], "description": "Get the authenticated user. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } }, "/variations": { "get": { "operationId": "get_variations", "tags": [ "Variations" ], "parameters": [ { "name": "page[number]", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "page[size]", "in": "query", "description": "Results per page. Values above the configured maximum are capped.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 30 }, "example": 1 }, { "name": "sort", "in": "query", "description": "Comma-separated sort fields; prefix a field with - for descending order. Allowed: name, traffic_percentage, is_baseline.", "schema": { "type": "string" }, "x-allowed-values": [ "name", "traffic_percentage", "is_baseline" ], "example": "example" }, { "name": "filter[id]", "in": "query", "description": "Filter by id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[project_id]", "in": "query", "description": "Filter by project_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[experiment_id]", "in": "query", "description": "Filter by experiment_id. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[name]", "in": "query", "description": "Filter by name. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" }, { "name": "filter[is_baseline]", "in": "query", "description": "Filter by is_baseline. Values use the endpoint’s configured matching; comma-separated values are supported by standard exact filters.", "schema": { "type": "string" }, "example": "example" } ], "responses": { "200": { "description": "Array of `VariationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VariationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] }, "example": { "data": [ { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } ], "links": { "first": null, "last": null, "prev": null, "next": null }, "meta": { "current_page": 1, "from": null, "last_page": 1, "links": [ { "url": null, "label": "example", "active": true } ], "path": null, "per_page": 1, "to": null, "total": 1 } } } } }, "400": { "description": "Unsupported filter, sort, or include.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Requested query option is not allowed." } }, "required": [ "message" ] }, "example": { "message": "Requested query option is not allowed." } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List variations", "description": "List variations. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "post": { "operationId": "post_variations", "tags": [ "Variations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVariationRequest" }, "example": { "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate" } } } }, "responses": { "201": { "description": "`VariationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VariationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Create variation", "description": "Create variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/variations/{variation}": { "delete": { "operationId": "delete_variations_variation", "tags": [ "Variations" ], "parameters": [ { "name": "variation", "in": "path", "required": true, "description": "The variation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "project_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Project Id.", "example": 101 } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Delete variation", "description": "Delete variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "get": { "operationId": "get_variations_variation", "tags": [ "Variations" ], "parameters": [ { "name": "variation", "in": "path", "required": true, "description": "The variation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "`VariationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VariationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This action is unauthorized." } }, "required": [ "message" ] }, "example": { "message": "This action is unauthorized." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Get variation", "description": "Get variation. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } }, "patch": { "operationId": "patch_variations_variation", "tags": [ "Variations" ], "parameters": [ { "name": "variation", "in": "path", "required": true, "description": "The variation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVariationRequest" }, "example": { "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`VariationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VariationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update variation", "description": "Update variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } }, "put": { "operationId": "put_variations_variation", "tags": [ "Variations" ], "parameters": [ { "name": "variation", "in": "path", "required": true, "description": "The variation ID", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVariationRequest" }, "example": { "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate" } } } }, "responses": { "200": { "description": "`VariationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VariationResource" } }, "required": [ "data" ] }, "example": { "data": { "id": 101, "import_source": null, "import_source_ref": null, "import_source_id": null, "data_import_id": null, "imported_at": null, "project_id": 101, "experiment_id": 101, "name": "Checkout delivery estimate", "traffic_percentage": 1, "traffic_locked": true, "is_baseline": true, "external_id": null, "external_platform": null, "external_synced_at": null, "external_metadata": null, "created_at": null, "updated_at": null } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "402": { "description": "The Team is in read-only billing mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "subscription_required" }, "mode": { "type": "string", "const": "blocked" }, "message": { "type": "string", "example": "Your team is in read-only mode. Update billing to make changes." }, "grace_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "error", "mode", "message", "grace_period_ends_at" ] }, "example": { "error": "subscription_required", "mode": "blocked", "message": "Your team is in read-only mode. Update billing to make changes.", "grace_period_ends_at": null } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "example": { "message": "The request could not be completed.", "errors": { "name": [ "The name field is required." ] } } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "Update variation", "description": "Update variation. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.", "x-permissions": { "ability": "write", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation.", "billing": "Blocked billing mode rejects writes with 402." } } }, "/{type}/{id}/attachments": { "get": { "operationId": "get_type_id_attachments", "tags": [ "Attachments" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "experiments", "ideas", "insights", "variations" ] }, "description": "Type.", "example": "experiments" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Id.", "example": 101 } ], "responses": { "200": { "description": "Array of `AttachmentResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttachmentResource" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": 101, "project_id": 101, "name": null, "file_type": null, "file_size": null, "type": "image", "url": null, "attachable_type": "example", "attachable_id": 101, "created_at": null, "updated_at": null } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "403": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] }, "example": { "message": "The request could not be completed." } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After before retrying.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Too Many Attempts." } }, "required": [ "message" ] }, "example": { "message": "Too Many Attempts." } } }, "headers": { "Retry-After": { "description": "Seconds before retrying.", "schema": { "type": "integer" } } } } }, "summary": "List attachments", "description": "List attachments. Requires the REST `read` token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation.", "x-permissions": { "ability": "read", "team": "Token-bound Team", "authorization": "Additional role, entity-policy and plan requirements vary by operation." } } } }, "components": { "schemas": { "Activity": { "type": "object", "properties": { "id": { "type": "integer" }, "log_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "subject_type": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "causer_type": { "type": [ "string", "null" ] }, "causer_id": { "type": [ "integer", "null" ] }, "properties": { "$ref": "#/components/schemas/JsonContainer" }, "batch_uuid": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "log_name", "description", "subject_type", "event", "subject_id", "causer_type", "causer_id", "properties", "batch_uuid", "created_at", "updated_at" ], "title": "Activity" }, "ActivityResource": { "type": "object", "properties": { "id": { "type": "integer" }, "log_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "subject_type": { "type": [ "string", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "event": { "type": [ "string", "null" ] }, "causer_type": { "type": [ "string", "null" ] }, "causer_id": { "type": [ "integer", "null" ] }, "properties": { "$ref": "#/components/schemas/JsonContainer" }, "batch_uuid": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "anyOf": [ { "description": "Relationships", "$ref": "#/components/schemas/Activity" }, { "type": "null" } ] }, "causer": { "anyOf": [ { "$ref": "#/components/schemas/Activity" }, { "type": "null" } ] } }, "required": [ "id", "log_name", "description", "subject_type", "subject_id", "event", "causer_type", "causer_id", "properties", "batch_uuid", "created_at", "updated_at" ], "title": "ActivityResource" }, "AttachmentResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size": { "type": [ "integer", "null" ] }, "type": { "$ref": "#/components/schemas/AttachmentType" }, "url": { "type": [ "string", "null" ] }, "attachable_type": { "type": "string" }, "attachable_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "file_type", "file_size", "type", "url", "attachable_type", "attachable_id", "created_at", "updated_at" ], "title": "AttachmentResource" }, "AttachmentType": { "type": "string", "enum": [ "image", "document", "link" ], "title": "AttachmentType" }, "AudienceResource": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "$ref": "#/components/schemas/JsonContainer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "AudienceResource" }, "BulkExperimentActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkExperimentActionRequest" }, "BulkFormActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete", "publish", "change-status" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 }, "status": { "$ref": "#/components/schemas/FormStatus" } }, "required": [ "action", "ids" ], "title": "BulkFormActionRequest" }, "BulkIdeaActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkIdeaActionRequest" }, "BulkInsightActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkInsightActionRequest" }, "BulkLearningActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkLearningActionRequest" }, "BulkObservationActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "accept", "dismiss", "restore-dismissal", "archive", "delete", "duplicate" ] }, "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "action", "ids" ], "title": "BulkObservationActionRequest" }, "CommentResource": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/UserResource" }, { "type": "null" } ] }, "user_id": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "integer", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResource" } }, "is_approved": { "type": "boolean" }, "commentable_type": { "type": "string" }, "commentable_id": { "type": "integer" }, "can_edit": { "type": "boolean" }, "can_delete": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "body", "user_id", "parent_id", "is_approved", "commentable_type", "commentable_id", "can_edit", "can_delete", "created_at", "updated_at" ], "title": "CommentResource" }, "DuplicateFormsRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ], "title": "DuplicateFormsRequest" }, "ExperimentApprovalResource": { "type": "object", "properties": { "id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "user_id": { "type": "integer" }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "approved_at": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "avatar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "avatar" ] } }, "required": [ "id", "experiment_id", "user_id", "status", "notes", "approved_at", "created_at" ], "title": "ExperimentApprovalResource" }, "ExperimentDecision": { "type": "string", "enum": [ "implement", "rollout", "retest", "iterate", "reject" ], "title": "ExperimentDecision" }, "ExperimentReportResource": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "insufficient_data", "srm_detected", "incomplete_mapping", "unsupported_metric", "fixed_horizon_pending", "stale_source", "engine_unavailable", "invalid_configuration", "no_data" ] }, "status_reason": { "type": [ "string", "null" ] }, "alpha": { "type": [ "number", "null" ] }, "control_variation_id": { "type": [ "integer", "null" ] }, "method": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "const": "fixed_horizon_v1" }, "version": { "type": "string", "const": "1.0.0" }, "multiple_comparison_correction": { "type": "string", "const": "holm" } }, "required": [ "name", "version", "multiple_comparison_correction" ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "integration_id": { "type": "integer" }, "external_updated_at": { "type": [ "string", "null" ] }, "synced_at": { "type": [ "string", "null" ] } }, "required": [ "integration_id", "external_updated_at", "synced_at" ] }, { "type": "null" } ] }, "primary_metric": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "external_id": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "type", "external_id" ] }, { "type": "null" } ] }, "totals": { "type": "object", "properties": { "visitors": { "type": "integer" }, "conversions": { "type": "integer" }, "conversion_rate_percent": { "type": [ "number", "null" ] } }, "required": [ "visitors", "conversions", "conversion_rate_percent" ] }, "srm": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "insufficient_data" ] }, "alpha": { "type": "number" }, "chi_square": { "type": [ "number", "null" ] }, "degrees_of_freedom": { "type": "integer" }, "p_value": { "type": [ "number", "null" ] }, "is_srm": { "type": "boolean" }, "expected_counts": { "type": "array", "items": { "type": "number" } } }, "required": [ "status", "alpha", "chi_square", "degrees_of_freedom", "p_value", "is_srm", "expected_counts" ] }, { "type": "null" } ] }, "variations": { "type": "array", "items": { "type": "object", "properties": { "variation_id": { "type": "integer" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "traffic_percentage": { "type": "number", "description": "Traffic share as a fraction: 0.5 means 50%." }, "visitors": { "type": "integer" }, "conversions": { "type": "integer" }, "conversion_rate_percent": { "type": [ "number", "null" ] }, "comparison_status": { "type": [ "string", "null" ], "enum": [ "available", "insufficient_data", null ] }, "test_method": { "type": [ "string", "null" ], "enum": [ "two_proportion_z", "fisher_exact", null ] }, "statistic": { "type": [ "number", "null" ] }, "p_value": { "type": [ "number", "null" ] }, "adjusted_p_value": { "type": [ "number", "null" ] }, "is_significant": { "type": [ "boolean", "null" ] }, "absolute_lift_percentage_points": { "type": [ "number", "null" ] }, "relative_lift_percent": { "type": [ "number", "null" ] }, "confidence_interval_percentage_points": { "anyOf": [ { "type": "object", "properties": { "lower": { "type": "number" }, "upper": { "type": "number" }, "confidence_level": { "type": "number" } }, "required": [ "lower", "upper", "confidence_level" ] }, { "type": "null" } ] } }, "required": [ "variation_id", "external_id", "name", "is_control", "traffic_percentage", "visitors", "conversions", "conversion_rate_percent", "comparison_status", "test_method", "statistic", "p_value", "adjusted_p_value", "is_significant", "absolute_lift_percentage_points", "relative_lift_percent", "confidence_interval_percentage_points" ] } } }, "required": [ "status", "status_reason", "alpha", "control_variation_id", "method", "source", "primary_metric", "totals", "srm", "variations" ], "description": "Fixed-horizon experiment report. Check status before interpreting significance; descriptive totals remain available for some unavailable states. Rates/lifts ending in percent use percent units; traffic_percentage uses a fraction.", "example": { "status": "no_data", "status_reason": "No synced experiment result is available.", "alpha": null, "control_variation_id": null, "method": null, "source": null, "primary_metric": null, "totals": { "visitors": 0, "conversions": 0, "conversion_rate_percent": null }, "srm": null, "variations": [] } }, "ExperimentResource": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "type": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentType" }, { "type": "null" } ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "primary_metric_id": { "type": [ "integer", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "stop_reason": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentStopReason" }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentResult" }, { "type": "null" } ] }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentDecision" }, { "type": "null" } ] }, "learning": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "$ref": "#/components/schemas/JsonContainer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_approval": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentApprovalResource" }, { "type": "null" } ] }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentApprovalResource" } } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "type", "state_id", "name", "description", "hypothesis", "primary_metric_id", "start_date", "end_date", "stop_reason", "result", "decision", "learning", "user_id", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "ExperimentResource" }, "ExperimentResult": { "type": "string", "enum": [ "conclusive_winner", "conclusive_loser", "inconclusive", "error", "other" ], "title": "ExperimentResult" }, "ExperimentStateCategory": { "type": "string", "enum": [ "draft", "live", "paused", "finished", "archived" ], "title": "ExperimentStateCategory" }, "ExperimentStateResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "category": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentStateCategory" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "category", "order", "created_at", "updated_at" ], "title": "ExperimentStateResource" }, "ExperimentStopReason": { "type": "string", "enum": [ "hypothesis_rejected", "hypothesis_iteration", "user_feedback", "data_issue", "implementation_issue", "experiment_setup_issue", "guardrail_metric_impact", "secondary_metric_impact", "operational_decision", "performance_issue", "testing", "tracking_issue", "other" ], "title": "ExperimentStopReason" }, "ExperimentTimeseriesResource": { "type": "object", "properties": { "variation_id": { "type": "integer" }, "name": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "format": "date" }, "visitors": { "type": "integer", "minimum": 0 }, "conversions": { "type": "integer", "minimum": 0 }, "conversion_rate": { "type": [ "number", "null" ], "description": "Conversion rate as a percentage, not a fraction." } }, "required": [ "date", "visitors", "conversions", "conversion_rate" ] } } }, "required": [ "variation_id", "name", "points" ] }, "ExperimentType": { "type": "string", "enum": [ "ab_test", "multivariate_test" ], "title": "ExperimentType" }, "FormAnswerResource": { "type": "object", "properties": { "id": { "type": "integer" }, "form_response_id": { "type": "integer" }, "form_question_id": { "type": "integer" }, "value": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_response_id", "form_question_id", "value", "created_at", "updated_at" ], "title": "FormAnswerResource" }, "FormQuestionResource": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "form_step_id": { "type": [ "integer", "null" ] }, "type": { "$ref": "#/components/schemas/FormQuestionType" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/JsonValue" }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "$ref": "#/components/schemas/JsonContainer" }, "order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "form_step_id", "type", "title", "description", "options", "settings", "order", "created_at", "updated_at" ], "title": "FormQuestionResource" }, "FormQuestionType": { "type": "string", "enum": [ "multiple_choice_single", "multiple_choice_multi", "rating", "nps", "short_text", "long_text", "yes_no", "emoji_reaction", "welcome_screen", "thank_you_screen" ], "title": "FormQuestionType" }, "FormResource": { "type": "object", "properties": { "id": { "type": "integer" }, "public_id": { "type": "string" }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/FormType" }, "status": { "$ref": "#/components/schemas/FormStatus" }, "settings": { "$ref": "#/components/schemas/JsonContainer" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FormStepResource" } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/FormQuestionResource" } }, "responses_count": { "type": "integer" }, "submitted_responses_count": { "type": "integer", "minimum": 0 }, "partial_responses_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "public_id", "project_id", "name", "description", "type", "status", "settings", "created_at", "updated_at" ], "title": "FormResource" }, "FormResponseResource": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "response_key": { "type": [ "string", "null" ] }, "respondent_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "page_url": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "viewport_width": { "type": [ "integer", "null" ] }, "viewport_height": { "type": [ "integer", "null" ] }, "screen_width": { "type": [ "integer", "null" ] }, "screen_height": { "type": [ "integer", "null" ] }, "client_type": { "type": [ "string", "null" ] }, "browser_name": { "type": [ "string", "null" ] }, "browser_version": { "type": [ "string", "null" ] }, "os_name": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "device_type": { "type": [ "string", "null" ] }, "is_bot": { "type": "boolean" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/FormAnswerResource" } }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "response_key", "respondent_id", "status", "page_url", "user_agent", "referrer", "language", "timezone", "viewport_width", "viewport_height", "screen_width", "screen_height", "client_type", "browser_name", "browser_version", "os_name", "os_version", "device_type", "is_bot", "submitted_at", "created_at", "updated_at" ], "title": "FormResponseResource" }, "FormResponseStatus": { "type": "string", "enum": [ "partial", "submitted" ], "title": "FormResponseStatus" }, "FormStatus": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "title": "FormStatus" }, "FormStepResource": { "type": "object", "properties": { "id": { "type": "integer" }, "form_id": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/FormQuestionResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "form_id", "title", "description", "order", "created_at", "updated_at" ], "title": "FormStepResource" }, "FormType": { "type": "string", "enum": [ "widget", "inline", "link" ], "title": "FormType" }, "IdeaResource": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "$ref": "#/components/schemas/IdeaSourceType" }, { "type": "null" } ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_name": { "type": [ "string", "null" ] }, "priority_values": { "$ref": "#/components/schemas/JsonContainer" }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "$ref": "#/components/schemas/JsonContainer" }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "state": { "anyOf": [ { "$ref": "#/components/schemas/IdeaStateResource" }, { "type": "null" } ] }, "audiences": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceResource" } }, "experiments": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentResource" } }, "insights": { "type": "array", "items": { "$ref": "#/components/schemas/InsightResource" } }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResource" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/PageResource" } }, "experiments_count": { "type": "integer" }, "insights_count": { "type": "integer" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "project_id", "state_id", "name", "description", "hypothesis", "user_id", "source", "source_id", "source_item_key", "source_name", "priority_values", "priority_score", "priority_details", "priority_calculated_at", "created_at", "updated_at" ], "title": "IdeaResource" }, "IdeaSourceType": { "type": "string", "enum": [ "audit", "insight", "experiment", "form", "api" ], "title": "IdeaSourceType" }, "IdeaStateColor": { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "IdeaStateColor" }, "IdeaStateResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "$ref": "#/components/schemas/IdeaStateColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "color", "order", "created_at", "updated_at" ], "title": "IdeaStateResource" }, "InsightLabelColor": { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "InsightLabelColor" }, "InsightLabelResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "color": { "anyOf": [ { "$ref": "#/components/schemas/InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "color", "order", "created_at", "updated_at", "deleted_at" ], "title": "InsightLabelResource" }, "InsightResource": { "type": "object", "properties": { "id": { "type": "integer" }, "custom_id": { "type": [ "string", "null" ] }, "numbering_scheme_id": { "type": [ "integer", "null" ] }, "custom_id_number": { "type": [ "integer", "null" ] }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_ideas": { "type": "boolean" } }, "required": [ "id", "custom_id", "numbering_scheme_id", "custom_id_number", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "research_collection_id", "insight_label_id", "user_id", "source", "source_id", "source_item_key", "source_label", "name", "description", "created_at", "updated_at", "deleted_at", "has_ideas" ], "title": "InsightResource" }, "JsonContainer": { "description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.", "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ] }, "JsonValue": { "description": "An arbitrary JSON value retained by a metadata/settings field.", "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "LearningResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "confidence": { "type": [ "string", "null" ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "confidence", "learned_at", "created_at", "updated_at", "deleted_at" ], "title": "LearningResource" }, "MetricResource": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "anyOf": [ { "$ref": "#/components/schemas/MetricType" }, { "type": "null" } ] }, "winning_direction": { "anyOf": [ { "$ref": "#/components/schemas/MetricWinningDirection" }, { "type": "null" } ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "$ref": "#/components/schemas/JsonContainer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "type", "winning_direction", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "MetricResource" }, "MetricType": { "type": "string", "enum": [ "average-per-user", "rate-per-user", "average-per-session", "rate-per-session" ], "title": "MetricType" }, "MetricWinningDirection": { "type": "string", "enum": [ "increasing", "decreasing" ], "title": "MetricWinningDirection" }, "NumberingSchemeInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "scope": { "type": "string", "enum": [ "team", "project" ] }, "template": { "type": "string", "maxLength": 120, "description": "Identifier template, for example EXP-{number:000}. Project-scoped templates may include {project_code}." }, "initial_number": { "type": "integer", "minimum": 1 }, "is_active": { "type": "boolean" }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "experiments", "ideas", "insights" ] }, "project_id": { "type": [ "integer", "null" ] } }, "required": [ "entity_type" ] } } }, "example": { "name": "Experiment IDs", "scope": "team", "template": "EXP-{number:000}", "initial_number": 1, "assignments": [ { "entity_type": "experiments" } ] } }, "ObservationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "integer", "null" ] }, "source_item_key": { "type": [ "string", "null" ] }, "source_label": { "type": [ "string", "null" ] }, "evidence_kind": { "type": [ "string", "null" ] }, "evidence_payload": { "$ref": "#/components/schemas/JsonContainer" }, "confidence": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "locked": { "type": "boolean" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_by": { "type": [ "integer", "null" ] }, "dismissed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dismissed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "review_status": { "type": "string" } }, "required": [ "id", "project_id", "research_collection_id", "user_id", "name", "description", "source_type", "source_id", "source_item_key", "source_label", "evidence_kind", "evidence_payload", "confidence", "observed_at", "locked", "accepted_at", "accepted_by", "dismissed_at", "dismissed_by", "created_at", "updated_at", "deleted_at", "review_status" ], "title": "ObservationResource" }, "ObservationReviewFilter": { "type": "string", "enum": [ "active", "pending", "dismissed", "archived", "all" ], "title": "ObservationReviewFilter" }, "OrderExperimentStateRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ], "title": "OrderExperimentStateRequest" }, "OrderIdeaStateRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ], "title": "OrderIdeaStateRequest" }, "PageResource": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "$ref": "#/components/schemas/JsonContainer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "description", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at", "deleted_at" ], "title": "PageResource" }, "PrioModelResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/JsonValue" }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "default_config", "created_at", "updated_at" ], "title": "PrioModelResource" }, "ProjectColor": { "type": "string", "enum": [ "gray", "red", "orange", "green", "blue", "purple", "rose" ], "title": "ProjectColor" }, "ProjectResource": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "state": { "anyOf": [ { "$ref": "#/components/schemas/ProjectState" }, { "type": "null" } ] }, "name": { "type": "string" }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "color": { "anyOf": [ { "$ref": "#/components/schemas/ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "public_id", "state", "name", "cover", "color", "prio_model_id", "created_at", "updated_at" ], "title": "ProjectResource" }, "ProjectState": { "type": "string", "enum": [ "active", "archived" ], "title": "ProjectState" }, "RecalculatePrioModelRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "id": { "type": "integer" } }, "required": [ "project_id", "id" ], "title": "RecalculatePrioModelRequest" }, "ResearchCollectionResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ], "description": "URL of the uploaded cover, or null." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "name", "description", "cover", "created_at", "updated_at" ], "title": "ResearchCollectionResource" }, "RoadmapAnnotationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "type": { "$ref": "#/components/schemas/RoadmapAnnotationType" }, "annotation_type": { "type": "string" }, "label": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "type", "annotation_type", "label", "start_date", "end_date", "notes", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "RoadmapAnnotationResource" }, "RoadmapAnnotationType": { "type": "string", "enum": [ "overlay", "marker" ], "title": "RoadmapAnnotationType" }, "ScreenAnnotationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "insight_label_id": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] }, "x": { "type": [ "integer", "null" ] }, "y": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "shape": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonContainer" }, "user_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "screen_id", "insight_label_id", "note", "x", "y", "width", "height", "shape", "metadata", "user_id", "created_at", "updated_at", "deleted_at" ], "title": "ScreenAnnotationResource" }, "ScreenResource": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "width": { "type": [ "string", "null" ] }, "height": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "project_id", "research_collection_id", "audience_id", "page_id", "name", "description", "image", "width", "height", "created_at", "updated_at", "deleted_at" ], "title": "ScreenResource" }, "StoreAttachmentRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "type": { "$ref": "#/components/schemas/AttachmentType" }, "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 10240 kilobytes." }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "attachable_type": { "type": "string", "enum": [ "experiment", "idea", "insight", "variation" ] }, "attachable_id": { "type": "integer" } }, "required": [ "project_id", "type", "attachable_type", "attachable_id" ], "title": "StoreAttachmentRequest", "description": "For image/document attachments, file is required (up to 10 MB; JPEG, PNG, GIF, PDF, DOC/DOCX, XLS/XLSX). For link attachments, url is required. The linked record must exist in this Team.", "allOf": [ { "if": { "properties": { "type": { "enum": [ "image", "document" ] } }, "required": [ "type" ] }, "then": { "required": [ "file" ] } }, { "if": { "properties": { "type": { "const": "link" } }, "required": [ "type" ] }, "then": { "required": [ "url" ] } } ], "example": { "project_id": 101, "type": "link", "url": "https://example.com/research", "attachable_type": "idea", "attachable_id": 101 } }, "StoreAudienceRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "required": [ "project_id", "name" ], "title": "StoreAudienceRequest" }, "StoreCommentRequest": { "type": "object", "properties": { "commentable_type": { "type": "string", "enum": [ "insight", "idea", "experiment" ] }, "commentable_id": { "type": "integer", "minimum": 1 }, "body": { "type": "string", "maxLength": 5000 }, "parent_id": { "type": [ "integer", "null" ] } }, "required": [ "commentable_type", "commentable_id", "body" ], "title": "StoreCommentRequest" }, "StoreExperimentRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ExperimentType" }, "state_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "primary_metric_id": { "type": [ "integer", "null" ] }, "secondary_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "guardrail_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "type", "name" ], "title": "StoreExperimentRequest" }, "StoreExperimentStateRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "category": { "$ref": "#/components/schemas/ExperimentStateCategory" } }, "required": [ "project_id", "name", "category" ], "title": "StoreExperimentStateRequest" }, "StoreFormRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/FormType" }, "status": { "$ref": "#/components/schemas/FormStatus" }, "project_id": { "type": "integer" }, "settings": { "$ref": "#/components/schemas/JsonContainer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FormQuestionType" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/JsonValue" }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "$ref": "#/components/schemas/JsonContainer" }, "order": { "type": "integer" } }, "required": [ "type", "title" ] } } } } } }, "required": [ "name", "project_id" ], "title": "StoreFormRequest" }, "StoreIdeaRequest": { "type": "object", "properties": { "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "source_name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "metric_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "priority_values": { "$ref": "#/components/schemas/JsonContainer" }, "priority_score": { "type": [ "number", "null" ] }, "priority_details": { "$ref": "#/components/schemas/JsonContainer" }, "priority_calculated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "name", "project_id" ], "title": "StoreIdeaRequest" }, "StoreIdeaStateRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "color": { "type": "string", "maxLength": 255 } }, "required": [ "project_id", "name", "color" ], "title": "StoreIdeaStateRequest" }, "StoreInsightLabelRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "color": { "$ref": "#/components/schemas/InsightLabelColor" } }, "required": [ "project_id", "name", "color" ], "title": "StoreInsightLabelRequest" }, "StoreInsightRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "source": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "project_id": { "type": "integer" }, "user_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "observation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "learning_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotations": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "required": [ "name", "project_id" ], "title": "StoreInsightRequest" }, "StoreLearningRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "required": [ "project_id", "name" ], "title": "StoreLearningRequest" }, "StoreMetricRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "winning_direction": { "$ref": "#/components/schemas/MetricWinningDirection" }, "type": { "$ref": "#/components/schemas/MetricType" } }, "required": [ "project_id", "name", "winning_direction", "type" ], "title": "StoreMetricRequest" }, "StoreObservationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "source_type": { "type": [ "string", "null" ], "enum": [ "manual", "audit", "experiment", "survey", "screen", "import", "external_research", null ] }, "source_id": { "type": [ "integer", "null" ], "minimum": 1 }, "source_item_key": { "type": [ "string", "null" ], "maxLength": 255 }, "source_label": { "type": [ "string", "null" ], "maxLength": 255 }, "evidence_kind": { "type": [ "string", "null" ], "enum": [ "screenshot_region", "quote", "metric_result", "page_text", "manual_note", "audit_observation", null ] }, "evidence_payload": { "$ref": "#/components/schemas/JsonContainer" }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "required": [ "project_id", "name" ], "title": "StoreObservationRequest" }, "StorePageRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "required": [ "project_id", "name" ], "title": "StorePageRequest" }, "StorePrioModelRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/JsonValue" }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] } }, "required": [ "name", "default_config" ], "title": "StorePrioModelRequest", "example": { "name": "ICE", "default_config": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } } }, "StoreProjectRequest": { "type": "object", "properties": { "state": { "anyOf": [ { "$ref": "#/components/schemas/ProjectState" }, { "type": "null" } ] }, "name": { "type": "string", "maxLength": 255 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 25600 kilobytes." }, "color": { "anyOf": [ { "$ref": "#/components/schemas/ProjectColor" }, { "type": "null" } ] } }, "required": [ "name" ], "title": "StoreProjectRequest" }, "StoreResearchCollectionRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." } }, "required": [ "project_id", "name" ], "title": "StoreResearchCollectionRequest" }, "StoreRoadmapAnnotationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "type": { "$ref": "#/components/schemas/RoadmapAnnotationType" }, "annotation_type": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 255 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "required": [ "project_id", "type", "annotation_type", "label", "start_date" ], "title": "StoreRoadmapAnnotationRequest" }, "StoreScreenAnnotationsRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "screen_id": { "type": "integer" }, "note": { "type": [ "string", "null" ], "maxLength": 65535 }, "insight_label_id": { "type": "integer" }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 }, "shape": { "type": "string", "enum": [ "point", "rect" ] }, "metadata": { "$ref": "#/components/schemas/JsonContainer" } }, "required": [ "project_id", "screen_id", "x", "y" ], "title": "StoreScreenAnnotationsRequest" }, "StoreScreenRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "image": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 25600 kilobytes." } }, "required": [ "project_id", "name", "image" ], "title": "StoreScreenRequest" }, "StoreTagRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "type": { "$ref": "#/components/schemas/TagType" }, "description": { "type": [ "string", "null" ] } }, "required": [ "project_id", "name", "type" ], "title": "StoreTagRequest" }, "StoreVariationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "traffic_percentage": { "type": "number", "minimum": 0, "maximum": 1 }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" } }, "required": [ "project_id", "experiment_id", "name" ], "title": "StoreVariationRequest" }, "TagResource": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/TagType" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "name", "type", "description", "created_at", "updated_at" ], "title": "TagResource" }, "TagType": { "type": "string", "enum": [ "generic", "page", "device", "insight-detail-type", "audience" ], "title": "TagType" }, "UpdateAttachmentRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } }, "title": "UpdateAttachmentRequest" }, "UpdateAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "title": "UpdateAudienceRequest" }, "UpdateCommentRequest": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 5000 } }, "required": [ "body" ], "title": "UpdateCommentRequest" }, "UpdateExperimentRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ExperimentType" }, "state_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": "integer" }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "primary_metric_id": { "type": "integer" }, "secondary_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "guardrail_metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "uniqueItems": true }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } }, "title": "UpdateExperimentRequest" }, "UpdateExperimentStateRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "category": { "$ref": "#/components/schemas/ExperimentStateCategory" }, "order": { "type": "integer", "minimum": 0 } }, "title": "UpdateExperimentStateRequest" }, "UpdateFormRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/FormType" }, "status": { "$ref": "#/components/schemas/FormStatus" }, "project_id": { "type": "integer" }, "settings": { "$ref": "#/components/schemas/JsonContainer" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "order": { "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "$ref": "#/components/schemas/FormQuestionType" }, "title": { "type": "string", "maxLength": 500 }, "description": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/JsonValue" }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "settings": { "$ref": "#/components/schemas/JsonContainer" }, "order": { "type": "integer" } }, "required": [ "type", "title" ] } } } } } }, "title": "UpdateFormRequest" }, "UpdateIdeaRequest": { "type": "object", "properties": { "state_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "source": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "hypothesis": { "type": [ "string", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "project_id": { "type": "integer" }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "metric_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "priority_values": { "$ref": "#/components/schemas/JsonContainer" } }, "title": "UpdateIdeaRequest" }, "UpdateIdeaStateRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "color": { "type": [ "string", "null" ], "maxLength": 255 }, "order": { "type": [ "integer", "null" ], "minimum": 0 } }, "title": "UpdateIdeaStateRequest" }, "UpdateInsightLabelRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "color": { "anyOf": [ { "$ref": "#/components/schemas/InsightLabelColor" }, { "type": "null" } ] }, "order": { "type": [ "integer", "null" ] } }, "title": "UpdateInsightLabelRequest" }, "UpdateInsightRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "source": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "insight_label_id": { "type": [ "integer", "null" ] }, "audience_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "experiment_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "idea_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "observation_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "learning_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } }, "screen_annotations": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] } } }, "title": "UpdateInsightRequest" }, "UpdateLearningRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "learned_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "title": "UpdateLearningRequest" }, "UpdateMetricRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "winning_direction": { "$ref": "#/components/schemas/MetricWinningDirection" }, "type": { "$ref": "#/components/schemas/MetricType" } }, "title": "UpdateMetricRequest" }, "UpdateObservationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "source_type": { "type": [ "string", "null" ], "enum": [ "manual", "audit", "experiment", "survey", "screen", "import", "external_research", null ] }, "source_id": { "type": [ "integer", "null" ], "minimum": 1 }, "source_item_key": { "type": [ "string", "null" ], "maxLength": 255 }, "source_label": { "type": [ "string", "null" ], "maxLength": 255 }, "evidence_kind": { "type": [ "string", "null" ], "enum": [ "screenshot_region", "quote", "metric_result", "page_text", "manual_note", "audit_observation", null ] }, "evidence_payload": { "$ref": "#/components/schemas/JsonContainer" }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", "low", "unknown", null ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "insight_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "screen_annotation_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "page_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } } }, "title": "UpdateObservationRequest" }, "UpdatePageRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "title": "UpdatePageRequest" }, "UpdatePrioModelRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "default_config": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "key": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "boolean", "select" ] }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/JsonValue" }, "description": "Question options retained as JSON. The editor uses strings or objects with value and label.", "example": [ "Delivery time", "Shipping cost" ] }, "default": { "type": [ "string", "null" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] } }, "required": [ "name", "key", "type" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ] } }, "required": [ "name", "default_config" ], "title": "UpdatePrioModelRequest" }, "UpdateProjectRequest": { "type": "object", "properties": { "state": { "anyOf": [ { "$ref": "#/components/schemas/ProjectState" }, { "type": "null" } ] }, "name": { "type": "string", "maxLength": 255, "description": "Must be unique among projects in this Team, excluding the project being updated." }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." }, "color": { "anyOf": [ { "$ref": "#/components/schemas/ProjectColor" }, { "type": "null" } ] }, "prio_model_id": { "type": [ "integer", "null" ] } }, "title": "UpdateProjectRequest" }, "UpdateResearchCollectionRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 }, "cover": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 1024 kilobytes." } }, "title": "UpdateResearchCollectionRequest" }, "UpdateRoadmapAnnotationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "type": { "$ref": "#/components/schemas/RoadmapAnnotationType" }, "annotation_type": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 255 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ] } }, "title": "UpdateRoadmapAnnotationRequest" }, "UpdateScreenAnnotationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "note": { "type": "string", "maxLength": 65535 }, "insight_label_id": { "type": "integer" }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 }, "width": { "type": [ "integer", "null" ], "minimum": 1 }, "height": { "type": [ "integer", "null" ], "minimum": 1 }, "shape": { "type": "string", "enum": [ "point", "rect" ] }, "metadata": { "$ref": "#/components/schemas/JsonContainer" } }, "title": "UpdateScreenAnnotationRequest" }, "UpdateScreenRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "research_collection_id": { "type": [ "integer", "null" ] }, "audience_id": { "type": [ "integer", "null" ] }, "page_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 65535 } }, "title": "UpdateScreenRequest" }, "UpdateTagRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] } }, "title": "UpdateTagRequest" }, "UpdateVariationRequest": { "type": "object", "properties": { "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "traffic_percentage": { "type": "number", "minimum": 0, "maximum": 1 }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" } }, "required": [ "project_id", "experiment_id" ], "title": "UpdateVariationRequest" }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_visited_team_id": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "avatar", "email", "timezone", "email_verified_at", "last_login_at", "last_visited_team_id", "created_at", "updated_at" ], "title": "User" }, "UserResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "seat_type": { "type": [ "string", "null" ] }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "email", "role", "seat_type", "email_verified_at", "created_at", "updated_at", "last_login_at" ], "title": "UserResource" }, "ValidatePrioModelFormulaRequest": { "type": "object", "properties": { "formula": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "number", "boolean" ] }, "weight": { "type": "number" } }, "required": [ "key", "type", "weight" ] }, "minItems": 1 } }, "required": [ "formula", "inputs" ], "title": "ValidatePrioModelFormulaRequest", "example": { "formula": "impact * confidence / effort", "inputs": [ { "name": "Impact", "key": "impact", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Confidence", "key": "confidence", "type": "number", "min": 1, "max": 10, "weight": 1 }, { "name": "Effort", "key": "effort", "type": "number", "min": 1, "max": 10, "weight": 1 } ] } }, "VariationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "import_source": { "type": [ "string", "null" ] }, "import_source_ref": { "type": [ "string", "null" ] }, "import_source_id": { "type": [ "string", "null" ] }, "data_import_id": { "type": [ "integer", "null" ] }, "imported_at": { "type": [ "string", "null" ] }, "project_id": { "type": "integer" }, "experiment_id": { "type": "integer" }, "name": { "type": "string" }, "traffic_percentage": { "type": "number" }, "traffic_locked": { "type": "boolean" }, "is_baseline": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ] }, "external_platform": { "type": [ "string", "null" ] }, "external_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_metadata": { "$ref": "#/components/schemas/JsonContainer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "import_source", "import_source_ref", "import_source_id", "data_import_id", "imported_at", "project_id", "experiment_id", "name", "traffic_percentage", "traffic_locked", "is_baseline", "external_id", "external_platform", "external_synced_at", "external_metadata", "created_at", "updated_at" ], "title": "VariationResource" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Team-scoped API key created in Team Settings → API Keys. REST read/write abilities are separate from MCP abilities." } } }, "security": [ { "bearerAuth": [] } ] }