{ "openapi": "3.0.3", "info": { "title": "Tines Stories API", "version": "1.0.0", "license": { "name": "Proprietary", "url": "https://www.tines.com/terms" } }, "servers": [ { "url": "https://{tenant_domain}", "description": "Your Tines tenant", "variables": { "tenant_domain": { "default": "your-tenant.tines.com", "description": "The domain of your Tines tenant. Self-hosted tenants and tenants with a custom domain should use their own domain." } } } ], "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "paths": { "/api/v1/actions": { "get": { "summary": "List actions", "operationId": "get_api_v1_actions", "description": "Retrieve a list of actions available in the Tines tenant.", "tags": [ "Actions" ], "parameters": [ { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given story" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] }, "description": "List actions for the given story mode (must be used with story_id)" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given team" }, { "name": "group_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given group" }, { "name": "action_type", "in": "query", "schema": { "type": "string", "enum": [ "Agents::CaseAgent", "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::FormAgent", "Agents::GroupAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::RecordAgent", "Agents::RunScriptAgent", "Agents::SendToStoryAgent", "Agents::TriggerAgent", "Agents::WebhookAgent" ] }, "description": "Filter actions by the given type" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given draft" }, { "name": "include_live_activity", "in": "query", "schema": { "type": "boolean" }, "description": "When true, includes live activity metrics like pending_action_runs_count. Defaults to false." }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/story_action" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create an action", "operationId": "post_api_v1_actions", "description": "Create an action. Story or group ID must be provided. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided.", "tags": [ "Actions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::TriggerAgent", "Agents::WebhookAgent", "Agents::SendToStoryAgent", "Agents::GroupAgent", "Agents::RunScriptAgent" ], "description": "Type of action to create" }, "name": { "type": "string", "description": "Name of the action" }, "options": { "type": "object", "description": "JSON options block of the action" }, "position": { "type": "object", "description": "An object describing the XY coordinates of the action on the story diagram" }, "story_id": { "type": "integer", "description": "ID of story to which the action should be added" }, "group_id": { "type": "integer", "description": "ID of group to which the action should be added" }, "description": { "type": "string", "description": "A user-defined description of the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled. Defaults to false." }, "source_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should receive emitted events from" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to source actions. Mutually exclusive with source_ids. Each object has source_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "receiver_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should emit events to" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids. Each object has receiver_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "schedule": { "type": "object", "description": "An object defining the cron schedule for the action" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails" }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored" }, "monitor_no_events_emitted": { "type": "integer", "description": "Duration in seconds. If no events are emitted in this time, a notification will be sent." }, "draft_id": { "type": "integer", "description": "ID of the draft to which the action should be added" } }, "required": [ "type", "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "The source or receiver link parameters are malformed, mutually exclusive, or contain an unsupported link type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/actions/{agent_id}/events": { "get": { "summary": "List events", "operationId": "get_api_v1_actions_by_agent_id_events", "description": "Retrieve a list of events. Also available nested under an action as /api/v1/actions/:agent_id/events. A response whose payloads exceed 200MB returns a 422 error.", "tags": [ "Events (v1)" ], "parameters": [ { "name": "agent_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the action whose events to retrieve" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the given team. When team_id and story_id are used together, story_id is ignored" }, { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the given story. When team_id and story_id are used together, story_id is ignored" }, { "name": "story_mode", "in": "query", "schema": { "type": "string" }, "description": "Set to test to retrieve events from the story's default test story. Only valid with story_id" }, { "name": "include_groups", "in": "query", "schema": { "type": "boolean" }, "description": "Include events from groups in the specified story. Only valid with story_id (defaults to false)" }, { "name": "since_id", "in": "query", "schema": { "type": "integer" }, "description": "Only retrieve events after this ID" }, { "name": "until_id", "in": "query", "schema": { "type": "integer" }, "description": "Only retrieve events until (and including) this ID" }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve events created after this time (ISO 8601 timestamp)" }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve events until this time (ISO 8601 timestamp)" }, { "name": "show_reemitted_events_only", "in": "query", "schema": { "type": "boolean" }, "description": "Only retrieve events that have been re-emitted (defaults to false)" }, { "name": "exclude_previous_event_payloads", "in": "query", "schema": { "type": "boolean" }, "description": "When true, each event's payload contains only its own output, excluding payloads received from upstream events (defaults to false)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20, maximum 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/event" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "The since or until parameter is not a valid date or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/EventPageTooLarge" } } } }, "/api/v1/actions/{id}": { "delete": { "summary": "Delete an action", "operationId": "delete_api_v1_actions_by_id", "description": "Delete a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an action", "operationId": "get_api_v1_actions_by_id", "description": "Retrieve details of a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" }, { "name": "include_live_activity", "in": "query", "schema": { "type": "boolean" }, "description": "When true, includes live activity metrics like pending_action_runs_count. Defaults to false." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } }, "patch": { "summary": "Update an action", "operationId": "patch_api_v1_actions_by_id", "description": "Update an action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action" }, "description": { "type": "string", "description": "A user-defined description of the action" }, "options": { "type": "object", "description": "JSON options block of the action" }, "position": { "type": "object", "description": "An object describing the XY coordinates of the action on the story diagram" }, "source_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should receive emitted events from" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to source actions. Mutually exclusive with source_ids. Each object has source_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "receiver_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should emit events to" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids. Each object has receiver_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "schedule": { "type": "object", "description": "An object defining the cron schedule for the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails. You must include monitor_all_events if updating this value." }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored. You must include monitor_failures if updating this value." }, "monitor_no_events_emitted": { "type": "integer", "description": "Duration in seconds. If no events are emitted in this time, a notification will be sent. You must include both monitor_failures and monitor_all_events if updating this value." }, "num_runs_to_save": { "type": "integer", "description": "Number of story runs to save for this action. Only applicable for Receive Email and Webhook actions." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "The source or receiver link parameters are invalid, or num_runs_to_save is used with an unsupported action type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an action", "operationId": "put_api_v1_actions_by_id", "description": "Update an action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action" }, "description": { "type": "string", "description": "A user-defined description of the action" }, "options": { "type": "object", "description": "JSON options block of the action" }, "position": { "type": "object", "description": "An object describing the XY coordinates of the action on the story diagram" }, "source_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should receive emitted events from" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to source actions. Mutually exclusive with source_ids. Each object has source_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "receiver_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should emit events to" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids. Each object has receiver_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "schedule": { "type": "object", "description": "An object defining the cron schedule for the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails. You must include monitor_all_events if updating this value." }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored. You must include monitor_failures if updating this value." }, "monitor_no_events_emitted": { "type": "integer", "description": "Duration in seconds. If no events are emitted in this time, a notification will be sent. You must include both monitor_failures and monitor_all_events if updating this value." }, "num_runs_to_save": { "type": "integer", "description": "Number of story runs to save for this action. Only applicable for Receive Email and Webhook actions." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "The source or receiver link parameters are invalid, or num_runs_to_save is used with an unsupported action type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/actions/{id}/clear_memory": { "delete": { "summary": "Clear an action's memory", "operationId": "delete_api_v1_actions_by_id_clear_memory", "description": "Clear all the values stored in an action's memory. Applicable for event transform actions in deduplicate or implode mode.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } } }, "/api/v1/actions/{id}/logs": { "get": { "summary": "List an action's logs", "operationId": "get_api_v1_actions_by_id_logs", "description": "List all logs emitted by a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" }, { "name": "level", "in": "query", "schema": { "type": "integer", "enum": [ 2, 3, 4 ] }, "description": "Filter logs by severity level (warning = 2, info = 3, error = 4). Pass a single value or multiple values." }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. Defaults to 20." }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "action_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Action log ID" }, "level": { "type": "integer", "description": "The severity level of the log (warning = 2, info = 3, error = 4)" }, "message": { "type": "string", "description": "The log message" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp representing creation date and time of the action log" }, "inbound_event": { "type": "object", "nullable": true, "description": "The inbound event for the action run" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/actions/{id}/remove_events": { "delete": { "summary": "Delete an action's events", "operationId": "delete_api_v1_actions_by_id_remove_events", "description": "Delete all events emitted by a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" }, { "name": "async_deletion", "in": "query", "schema": { "type": "boolean" }, "description": "Whether the deletion should be asynchronous by sending it to a background job" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "async_deletion is not true or false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/actions/{id}/remove_logs": { "delete": { "summary": "Delete an action's logs", "operationId": "delete_api_v1_actions_by_id_remove_logs", "description": "Delete all logs emitted by a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } } }, "/api/v1/actions/{id}/run": { "post": { "summary": "Run an action", "operationId": "post_api_v1_actions_by_id_run", "description": "Manually run a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } } }, "/api/v1/admin/action_egress_control_rules": { "get": { "summary": "List action egress control rules", "operationId": "get_api_v1_admin_action_egress_control_rules", "tags": [ "Admin > Action Egress Control Rules" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "admin/action_egress_control_rules": { "type": "array", "items": { "$ref": "#/components/schemas/action_egress_control_rule" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create an action egress control rule", "operationId": "post_api_v1_admin_action_egress_control_rules", "tags": [ "Admin > Action Egress Control Rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Rule description" }, "allowed_action_types": { "type": "array", "items": { "type": "string" }, "description": "Action types allowed to send traffic to the destination" }, "ip": { "type": "string", "description": "IP address or CIDR range the rule applies to" }, "fqdn": { "type": "string", "description": "Fully qualified domain name the rule applies to" } }, "required": [ "description", "allowed_action_types" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_egress_control_rule" } } } } } } }, "/api/v1/admin/action_egress_control_rules/{id}": { "delete": { "summary": "Delete an action egress control rule", "operationId": "delete_api_v1_admin_action_egress_control_rules_by_id", "tags": [ "Admin > Action Egress Control Rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The rule ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an action egress control rule", "operationId": "get_api_v1_admin_action_egress_control_rules_by_id", "tags": [ "Admin > Action Egress Control Rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The rule ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_egress_control_rule" } } } } } }, "patch": { "summary": "Update an action egress control rule", "operationId": "patch_api_v1_admin_action_egress_control_rules_by_id", "tags": [ "Admin > Action Egress Control Rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The rule ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Rule description" }, "allowed_action_types": { "type": "array", "items": { "type": "string" }, "description": "Action types allowed to send traffic to the destination" }, "ip": { "type": "string", "description": "IP address or CIDR range the rule applies to" }, "fqdn": { "type": "string", "description": "Fully qualified domain name the rule applies to" } }, "required": [ "description", "allowed_action_types" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_egress_control_rule" } } } } } }, "put": { "summary": "Update an action egress control rule", "operationId": "put_api_v1_admin_action_egress_control_rules_by_id", "tags": [ "Admin > Action Egress Control Rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The rule ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Rule description" }, "allowed_action_types": { "type": "array", "items": { "type": "string" }, "description": "Action types allowed to send traffic to the destination" }, "ip": { "type": "string", "description": "IP address or CIDR range the rule applies to" }, "fqdn": { "type": "string", "description": "Fully qualified domain name the rule applies to" } }, "required": [ "description", "allowed_action_types" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_egress_control_rule" } } } } } } }, "/api/v1/admin/custom_certificate_authority": { "patch": { "summary": "Set the custom certificate authority", "operationId": "patch_api_v1_admin_custom_certificate_authority", "description": "Set a custom certificate authority for use by all of your IMAP and HTTP Request actions.", "tags": [ "Admin > Custom certificate authority" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "PEM encoded X.509 public certificate (or certificate chain) of your certificate authority" }, "name": { "type": "string", "default": "default", "description": "Name of your custom certificate authority" } }, "required": [ "certificate" ] } } } }, "responses": { "200": { "description": "Empty response on success" } } }, "put": { "summary": "Set the custom certificate authority", "operationId": "put_api_v1_admin_custom_certificate_authority", "description": "Set a custom certificate authority for use by all of your IMAP and HTTP Request actions.", "tags": [ "Admin > Custom certificate authority" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "PEM encoded X.509 public certificate (or certificate chain) of your certificate authority" }, "name": { "type": "string", "default": "default", "description": "Name of your custom certificate authority" } }, "required": [ "certificate" ] } } } }, "responses": { "200": { "description": "Empty response on success" } } } }, "/api/v1/admin/ip_access_control_rules": { "get": { "summary": "List IP access control rules", "operationId": "get_api_v1_admin_ip_access_control_rules", "description": "List IP access control rules for the tenant. These only take effect if IP access control is enabled.", "tags": [ "Admin > IP access control rules" ], "parameters": [ { "name": "matching_ip", "in": "query", "schema": { "type": "string" }, "description": "An address or CIDR to filter rules and return only matching ones" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. Defaults to 20" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number. Defaults to 1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "admin/ip_access_control_rules": { "type": "array", "items": { "$ref": "#/components/schemas/ip_access_control_rule" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create an IP access control rule", "operationId": "post_api_v1_admin_ip_access_control_rules", "description": "Create a new IP access control rule.", "tags": [ "Admin > IP access control rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address or CIDR range of the rule" }, "description": { "type": "string", "description": "Human-readable description of the rule" } }, "required": [ "ip" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ip_access_control_rule" } } } } } } }, "/api/v1/admin/ip_access_control_rules/{id}": { "delete": { "summary": "Delete an IP access control rule", "operationId": "delete_api_v1_admin_ip_access_control_rules_by_id", "description": "Delete an existing IP access control rule.", "tags": [ "Admin > IP access control rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "IP access control rule ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an IP access control rule", "operationId": "get_api_v1_admin_ip_access_control_rules_by_id", "description": "Get an IP access control rule by ID.", "tags": [ "Admin > IP access control rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "IP access control rule ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ip_access_control_rule" } } } } } }, "patch": { "summary": "Update an IP access control rule", "operationId": "patch_api_v1_admin_ip_access_control_rules_by_id", "description": "Update an existing IP access control rule.", "tags": [ "Admin > IP access control rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "IP access control rule ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address or CIDR range of the rule" }, "description": { "type": "string", "description": "Human-readable description of the rule" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ip_access_control_rule" } } } } } }, "put": { "summary": "Update an IP access control rule", "operationId": "put_api_v1_admin_ip_access_control_rules_by_id", "description": "Update an existing IP access control rule.", "tags": [ "Admin > IP access control rules" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "IP access control rule ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address or CIDR range of the rule" }, "description": { "type": "string", "description": "Human-readable description of the rule" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ip_access_control_rule" } } } } } } }, "/api/v1/admin/license": { "get": { "summary": "Get license", "operationId": "get_api_v1_admin_license", "description": "Retrieve the current license details for the tenant. This endpoint is only available on self-hosted tenants.", "tags": [ "Admin > License" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/license" } } } }, "403": { "$ref": "#/components/responses/LicenseForbidden" }, "404": { "description": "The tenant has no license.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorObject" } } } } } }, "patch": { "summary": "Update license", "operationId": "patch_api_v1_admin_license", "description": "Update and apply a new license to the tenant, replacing the existing one. A license must already exist — use the create endpoint to apply the first license. This endpoint is only available on self-hosted tenants.", "tags": [ "Admin > License" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "license": { "type": "string", "description": "The signed license string" } }, "required": [ "license" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/license" } } } }, "403": { "$ref": "#/components/responses/LicenseForbidden" }, "404": { "description": "The tenant has no license yet. Use POST to apply the first one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorObject" } } } }, "422": { "$ref": "#/components/responses/InvalidLicense" } } }, "post": { "summary": "Create license", "operationId": "post_api_v1_admin_license", "description": "Upload and apply a new license to the tenant. A license must not already exist — use the update endpoint to replace an existing license. This endpoint is only available on self-hosted tenants.", "tags": [ "Admin > License" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "license": { "type": "string", "description": "The signed license string" } }, "required": [ "license" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/license" } } } }, "403": { "$ref": "#/components/responses/LicenseForbidden" }, "409": { "description": "The tenant already has a license. Use PUT to replace it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorObject" } } } }, "422": { "$ref": "#/components/responses/InvalidLicense" } } }, "put": { "summary": "Update license", "operationId": "put_api_v1_admin_license", "description": "Update and apply a new license to the tenant, replacing the existing one. A license must already exist — use the create endpoint to apply the first license. This endpoint is only available on self-hosted tenants.", "tags": [ "Admin > License" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "license": { "type": "string", "description": "The signed license string" } }, "required": [ "license" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/license" } } } }, "403": { "$ref": "#/components/responses/LicenseForbidden" }, "404": { "description": "The tenant has no license yet. Use POST to apply the first one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorObject" } } } }, "422": { "$ref": "#/components/responses/InvalidLicense" } } } }, "/api/v1/admin/roles": { "get": { "summary": "List roles", "operationId": "get_api_v1_admin_roles", "description": "Retrieve a list of roles (both default and custom) from the Tines tenant.", "tags": [ "Admin > Roles" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "admin/roles": { "type": "array", "items": { "$ref": "#/components/schemas/admin_role" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a role", "operationId": "post_api_v1_admin_roles", "description": "Create a custom role in the Tines tenant.", "tags": [ "Admin > Roles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Role name" }, "description": { "type": "string", "description": "A description of the role" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permission names to apply to the role" } }, "required": [ "name", "permissions" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_role" } } } } } } }, "/api/v1/admin/roles/{id}": { "delete": { "summary": "Delete a role", "operationId": "delete_api_v1_admin_roles_by_id", "description": "Delete a specific custom role from the Tines tenant.", "tags": [ "Admin > Roles" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID or name of the role" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a role", "operationId": "get_api_v1_admin_roles_by_id", "description": "Retrieve details of a specific (default or custom) role.", "tags": [ "Admin > Roles" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID or name of the role" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_role" } } } } } }, "patch": { "summary": "Update a role", "operationId": "patch_api_v1_admin_roles_by_id", "description": "Update a custom role in the Tines tenant.", "tags": [ "Admin > Roles" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID or name of the role" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Role description" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permission names to apply to the role" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_role" } } } } } }, "put": { "summary": "Update a role", "operationId": "put_api_v1_admin_roles_by_id", "description": "Update a custom role in the Tines tenant.", "tags": [ "Admin > Roles" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID or name of the role" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Role description" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permission names to apply to the role" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_role" } } } } } } }, "/api/v1/admin/scim_user_group_mapping": { "get": { "summary": "Get the SCIM user group mapping", "operationId": "get_api_v1_admin_scim_user_group_mapping", "description": "Get the SCIM user group mapping for the tenant.\n\n**Deprecated. Use the user provisioning mapping endpoint instead. See [replacement endpoint](/api/v1/admin/user_provisioning/mapping).**", "tags": [ "Admin > User provisioning" ], "deprecated": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_group_mapping": { "$ref": "#/components/schemas/user_group_mapping" } } } } } } } }, "post": { "summary": "Update the SCIM user group mapping", "operationId": "post_api_v1_admin_scim_user_group_mapping", "description": "Update the SCIM user group mapping for the tenant. The full user group mapping must be sent; appending a new mapping is not supported.\n\n**Deprecated. Use the user provisioning mapping endpoint instead. See [replacement endpoint](/api/v1/admin/user_provisioning/mapping).**", "tags": [ "Admin > User provisioning" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_group_mapping": { "$ref": "#/components/schemas/user_group_mapping" } }, "required": [ "user_group_mapping" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_group_mapping": { "$ref": "#/components/schemas/user_group_mapping" } } } } } }, "400": { "description": "A key in the mapping uses camelCase instead of snake_case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/smtp": { "delete": { "summary": "Delete SMTP configuration", "operationId": "delete_api_v1_admin_smtp", "description": "Delete the SMTP configuration saved through the API for your self-hosted tenant. This endpoint is accessible only to self-hosted customers. This removes only the API-managed configuration; the tenant then falls back to the SMTP settings from the environment.", "tags": [ "Admin > SMTP configuration" ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get SMTP configuration", "operationId": "get_api_v1_admin_smtp", "description": "Retrieve the SMTP configuration used by your self-hosted tenant to send email. This endpoint is accessible only to self-hosted customers. When no configuration has been saved through the API, the response returns the SMTP settings from the tenant environment.", "tags": [ "Admin > SMTP configuration" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "SMTP server address" }, "port": { "type": "integer", "description": "SMTP server port" }, "domain": { "type": "string", "nullable": true, "description": "Domain sent during the SMTP greeting" }, "user_name": { "type": "string", "nullable": true, "description": "User name used for SMTP authentication" }, "auth_type": { "type": "string", "nullable": true, "description": "Authentication mode. One of `plain`, `login`, or `cram_md5`" }, "encryption_mode": { "type": "string", "description": "Encryption mode. One of `none`, `tls`, `starttls_auto`, or `starttls_strict`" }, "verify_ssl_certificate": { "type": "boolean", "description": "Whether the SMTP server's TLS certificate is verified" }, "ca_path": { "type": "string", "nullable": true, "description": "Path to a directory of CA certificates on the self-hosted installation" }, "ca_file": { "type": "string", "nullable": true, "description": "Path to a CA certificate file on the self-hosted installation" }, "open_timeout": { "type": "integer", "description": "SMTP connection open timeout in seconds" }, "read_timeout": { "type": "integer", "description": "SMTP connection read timeout in seconds" }, "source": { "type": "string", "description": "Where the settings were loaded from. `database` means settings saved through this API; `environment` means no API-managed configuration exists and settings come from the tenant environment" }, "password_set": { "type": "boolean", "description": "Whether a password is configured. The password itself is never returned" }, "warnings": { "type": "object", "nullable": true, "description": "Configuration warnings keyed by field. Only present for database-managed settings that have warnings" } } } } } } } }, "patch": { "summary": "Update SMTP configuration", "operationId": "patch_api_v1_admin_smtp", "description": "Create or replace the SMTP configuration used by your self-hosted tenant to send email. This endpoint is accessible only to self-hosted customers. The request replaces the full configuration rather than updating individual fields, so include every value you want to keep. Because the password is never returned, it must be included whenever the configuration uses SMTP authentication.", "tags": [ "Admin > SMTP configuration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "SMTP server address. Maximum length: 255 characters" }, "port": { "type": "integer", "description": "SMTP server port. Must be an integer from 1 to 65535" }, "domain": { "type": "string", "description": "Domain sent during the SMTP greeting. Maximum length: 255 characters" }, "user_name": { "type": "string", "description": "User name used for SMTP authentication. Required when `auth_type` is set. Maximum length: 255 characters" }, "password": { "type": "string", "description": "Password used for SMTP authentication. Required when `auth_type` is set. Maximum length: 1024 characters" }, "auth_type": { "type": "string", "enum": [ "plain", "login", "cram_md5" ], "description": "Authentication mode. When omitted, Tines does not authenticate to the SMTP server" }, "encryption_mode": { "type": "string", "enum": [ "none", "tls", "starttls_auto", "starttls_strict" ], "description": "Encryption mode used to secure the SMTP connection" }, "verify_ssl_certificate": { "type": "boolean", "description": "Whether the SMTP server's TLS certificate is verified" }, "ca_path": { "type": "string", "description": "Path to a directory of CA certificates on the self-hosted installation. Maximum length: 4096 characters" }, "ca_file": { "type": "string", "description": "Path to a CA certificate file on the self-hosted installation. Takes precedence over `ca_path`. Maximum length: 4096 characters" }, "open_timeout": { "type": "integer", "default": "30", "description": "SMTP connection open timeout in seconds. An integer from 1 to 120" }, "read_timeout": { "type": "integer", "default": "30", "description": "SMTP connection read timeout in seconds. An integer from 1 to 120" } }, "required": [ "address", "port", "encryption_mode", "verify_ssl_certificate" ] } } } }, "responses": { "200": { "description": "Empty response on success, or an object describing configuration warnings when the saved configuration has warnings", "content": { "application/json": { "schema": { "type": "object", "properties": { "warnings": { "type": "object", "nullable": true, "description": "Configuration warnings keyed by field" } } } } } } } }, "put": { "summary": "Update SMTP configuration", "operationId": "put_api_v1_admin_smtp", "description": "Create or replace the SMTP configuration used by your self-hosted tenant to send email. This endpoint is accessible only to self-hosted customers. The request replaces the full configuration rather than updating individual fields, so include every value you want to keep. Because the password is never returned, it must be included whenever the configuration uses SMTP authentication.", "tags": [ "Admin > SMTP configuration" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "SMTP server address. Maximum length: 255 characters" }, "port": { "type": "integer", "description": "SMTP server port. Must be an integer from 1 to 65535" }, "domain": { "type": "string", "description": "Domain sent during the SMTP greeting. Maximum length: 255 characters" }, "user_name": { "type": "string", "description": "User name used for SMTP authentication. Required when `auth_type` is set. Maximum length: 255 characters" }, "password": { "type": "string", "description": "Password used for SMTP authentication. Required when `auth_type` is set. Maximum length: 1024 characters" }, "auth_type": { "type": "string", "enum": [ "plain", "login", "cram_md5" ], "description": "Authentication mode. When omitted, Tines does not authenticate to the SMTP server" }, "encryption_mode": { "type": "string", "enum": [ "none", "tls", "starttls_auto", "starttls_strict" ], "description": "Encryption mode used to secure the SMTP connection" }, "verify_ssl_certificate": { "type": "boolean", "description": "Whether the SMTP server's TLS certificate is verified" }, "ca_path": { "type": "string", "description": "Path to a directory of CA certificates on the self-hosted installation. Maximum length: 4096 characters" }, "ca_file": { "type": "string", "description": "Path to a CA certificate file on the self-hosted installation. Takes precedence over `ca_path`. Maximum length: 4096 characters" }, "open_timeout": { "type": "integer", "default": "30", "description": "SMTP connection open timeout in seconds. An integer from 1 to 120" }, "read_timeout": { "type": "integer", "default": "30", "description": "SMTP connection read timeout in seconds. An integer from 1 to 120" } }, "required": [ "address", "port", "encryption_mode", "verify_ssl_certificate" ] } } } }, "responses": { "200": { "description": "Empty response on success, or an object describing configuration warnings when the saved configuration has warnings", "content": { "application/json": { "schema": { "type": "object", "properties": { "warnings": { "type": "object", "nullable": true, "description": "Configuration warnings keyed by field" } } } } } } } } }, "/api/v1/admin/sync_destinations": { "get": { "summary": "List sync destinations", "operationId": "get_api_v1_admin_sync_destinations", "description": "Retrieve a paginated list of sync destinations configured on the tenant.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync_destinations": { "type": "array", "items": { "$ref": "#/components/schemas/sync_destination" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a sync destination", "operationId": "post_api_v1_admin_sync_destinations", "description": "Create a new sync destination and subscribe it to one or more stories.", "tags": [ "Admin > Sync destinations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_tenant_url": { "type": "string", "description": "Base URL of the destination tenant. Use the current tenant's URL for same-tenant sync" }, "destination_tenant_api_key": { "type": "string", "description": "Tines API key used to publish to the destination tenant. Required only when syncing to a remote tenant" }, "destination_team_id": { "type": "integer", "description": "ID of the team on the destination tenant that will own the synced stories" }, "team_id": { "type": "integer", "description": "ID of the team on the current tenant creating the sync" }, "story_ids": { "type": "array", "items": { "type": "integer" }, "description": "Story IDs from the current tenant to sync" }, "manual_sync_only": { "type": "boolean", "description": "When true, stories are only synced on manual trigger" } }, "required": [ "destination_tenant_url", "destination_team_id", "team_id", "story_ids" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sync_destination" } } } } } } }, "/api/v1/admin/sync_destinations/{id}": { "delete": { "summary": "Delete a sync destination", "operationId": "delete_api_v1_admin_sync_destinations_by_id", "description": "Remove a sync destination configuration. By default, synced stories on the destination tenant are also deleted. Stories synced to a destination with sync_mode set to draft_editable are always detached and preserved.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The sync destination ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keep_stories": { "type": "boolean", "description": "When false (default), synced stories are deleted from the destination. When true, stories are detached from the sync source and remain on the destination as independent stories. Stories synced to a destination with sync_mode set to draft_editable are always detached, regardless of this setting" } } } } } }, "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a sync destination", "operationId": "get_api_v1_admin_sync_destinations_by_id", "description": "Retrieve a single sync destination by ID.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The sync destination ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sync_destination" } } } } } }, "patch": { "summary": "Update a sync destination", "operationId": "patch_api_v1_admin_sync_destinations_by_id", "description": "Update an existing sync destination. Use this to rotate the API key, change which stories are synced, or toggle manual-only sync. The source team, destination team, and destination tenant URL cannot be changed after creation.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The sync destination ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_tenant_api_key": { "type": "string", "description": "Tines API key used to publish to the destination tenant. When omitted, the existing key is preserved" }, "story_ids": { "type": "array", "items": { "type": "integer" }, "description": "Story IDs from the current tenant to sync. Pass an empty array to remove all subscriptions. When omitted, existing subscriptions are preserved" }, "manual_sync_only": { "type": "boolean", "description": "When true, stories are only synced on manual trigger. When omitted, the existing value is preserved" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sync_destination" } } } } } }, "put": { "summary": "Update a sync destination", "operationId": "put_api_v1_admin_sync_destinations_by_id", "description": "Update an existing sync destination. Use this to rotate the API key, change which stories are synced, or toggle manual-only sync. The source team, destination team, and destination tenant URL cannot be changed after creation.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The sync destination ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_tenant_api_key": { "type": "string", "description": "Tines API key used to publish to the destination tenant. When omitted, the existing key is preserved" }, "story_ids": { "type": "array", "items": { "type": "integer" }, "description": "Story IDs from the current tenant to sync. Pass an empty array to remove all subscriptions. When omitted, existing subscriptions are preserved" }, "manual_sync_only": { "type": "boolean", "description": "When true, stories are only synced on manual trigger. When omitted, the existing value is preserved" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sync_destination" } } } } } } }, "/api/v1/admin/sync_destinations/{id}/manual_sync": { "post": { "summary": "Manually sync a sync destination", "operationId": "post_api_v1_admin_sync_destinations_by_id_manual_sync", "description": "Trigger an immediate push of all subscribed stories to the destination tenant.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The sync destination ID" } ], "responses": { "200": { "description": "Confirmation that the sync was initiated" } } } }, "/api/v1/admin/sync_destinations/{id}/story/{story_id}/sync": { "post": { "summary": "Manually sync a single story", "operationId": "post_api_v1_admin_sync_destinations_by_id_story_by_story_id_sync", "description": "Trigger an immediate push of a single subscribed story to the destination tenant.", "tags": [ "Admin > Sync destinations" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The sync destination ID" }, { "name": "story_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story to sync" } ], "responses": { "200": { "description": "Confirmation that the story sync was initiated" } } } }, "/api/v1/admin/templates": { "get": { "summary": "List templates", "operationId": "get_api_v1_admin_templates", "description": "Retrieve a list of private templates. Optionally search to filter results.", "tags": [ "Admin > Templates" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter templates. Matches against name, description, vendor, product, and action options" }, { "name": "folder_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return templates in the specified folder" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "admin/templates": { "type": "array", "items": { "$ref": "#/components/schemas/template" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a template", "operationId": "post_api_v1_admin_templates", "description": "Create a private template.", "tags": [ "Admin > Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Template description" }, "agent_type": { "type": "string", "enum": [ "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::TriggerAgent", "Agents::WebhookAgent", "Agents::SendToStoryAgent" ], "description": "Type of action to create" }, "agent_options": { "type": "object", "description": "Action options" }, "vendor": { "type": "string", "description": "Vendor name" }, "product": { "type": "string", "description": "Product name" }, "team_id": { "type": "integer", "description": "ID of the team to which the template belongs" }, "folder_id": { "type": "integer", "description": "ID of a template folder to place the template in, belonging to the same team as the template" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this template can be used. Defaults to TEAM when team_id is passed, GLOBAL otherwise" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Slugs of teams where this template can be used. Required to set read_access to SPECIFIC_TEAMS" }, "action_inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Input parameter name" }, "type": { "type": "string", "enum": [ "TEXT", "NUMBER", "BOOLEAN", "DATE", "OBJECT", "OPTION", "CODE", "CREDENTIAL" ], "description": "Input type" }, "required": { "type": "boolean", "description": "Whether the input is required. Must be true for CREDENTIAL type" }, "description": { "type": "string", "description": "Description of the input parameter" }, "default_value": { "type": "string", "description": "Default value for the input" }, "data": { "type": "object", "description": "Type-specific configuration, used by OBJECT, OPTION, and CODE types" } }, "required": [ "name", "type" ] }, "description": "Input parameters for the template" } }, "required": [ "name", "agent_type", "agent_options", "product" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } } } } }, "/api/v1/admin/templates/{id}": { "delete": { "summary": "Delete a template", "operationId": "delete_api_v1_admin_templates_by_id", "description": "Delete a private template by ID.", "tags": [ "Admin > Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The template ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a template", "operationId": "get_api_v1_admin_templates_by_id", "description": "Retrieve a private template.", "tags": [ "Admin > Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The template ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } } } }, "patch": { "summary": "Update a template", "operationId": "patch_api_v1_admin_templates_by_id", "description": "Update a private template.", "tags": [ "Admin > Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Template description" }, "agent_type": { "type": "string", "enum": [ "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::TriggerAgent", "Agents::WebhookAgent", "Agents::SendToStoryAgent" ], "description": "Type of action associated with the template" }, "agent_options": { "type": "object", "description": "Action options" }, "vendor": { "type": "string", "description": "Vendor name" }, "product": { "type": "string", "description": "Product name" }, "folder_id": { "type": "integer", "description": "ID of a template folder to place the template in. Set to null to remove from a folder. Unchanged if omitted" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this template can be used. Unchanged if omitted" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Slugs of teams where this template can be used. Required when setting read_access to SPECIFIC_TEAMS. Unchanged if omitted" }, "action_inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Input parameter name" }, "type": { "type": "string", "enum": [ "TEXT", "NUMBER", "BOOLEAN", "DATE", "OBJECT", "OPTION", "CODE", "CREDENTIAL" ], "description": "Input type" }, "required": { "type": "boolean", "description": "Whether the input is required. Must be true for CREDENTIAL type" }, "description": { "type": "string", "description": "Description of the input parameter" }, "default_value": { "type": "string", "description": "Default value for the input" }, "data": { "type": "object", "description": "Type-specific configuration, used by OBJECT, OPTION, and CODE types" } }, "required": [ "name", "type" ] }, "description": "Input parameters for the template" } }, "required": [ "name", "product" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } } } }, "put": { "summary": "Update a template", "operationId": "put_api_v1_admin_templates_by_id", "description": "Update a private template.", "tags": [ "Admin > Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "description": "Template description" }, "agent_type": { "type": "string", "enum": [ "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::TriggerAgent", "Agents::WebhookAgent", "Agents::SendToStoryAgent" ], "description": "Type of action associated with the template" }, "agent_options": { "type": "object", "description": "Action options" }, "vendor": { "type": "string", "description": "Vendor name" }, "product": { "type": "string", "description": "Product name" }, "folder_id": { "type": "integer", "description": "ID of a template folder to place the template in. Set to null to remove from a folder. Unchanged if omitted" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this template can be used. Unchanged if omitted" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Slugs of teams where this template can be used. Required when setting read_access to SPECIFIC_TEAMS. Unchanged if omitted" }, "action_inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Input parameter name" }, "type": { "type": "string", "enum": [ "TEXT", "NUMBER", "BOOLEAN", "DATE", "OBJECT", "OPTION", "CODE", "CREDENTIAL" ], "description": "Input type" }, "required": { "type": "boolean", "description": "Whether the input is required. Must be true for CREDENTIAL type" }, "description": { "type": "string", "description": "Description of the input parameter" }, "default_value": { "type": "string", "description": "Default value for the input" }, "data": { "type": "object", "description": "Type-specific configuration, used by OBJECT, OPTION, and CODE types" } }, "required": [ "name", "type" ] }, "description": "Input parameters for the template" } }, "required": [ "name", "product" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } } } } }, "/api/v1/admin/templates/{id}/move": { "post": { "summary": "Move a template", "operationId": "post_api_v1_admin_templates_by_id_move", "description": "Move a private template to a different team. This resets the template's access settings to team-only visibility.", "tags": [ "Admin > Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "ID of the team to move the template to" }, "folder_id": { "type": "integer", "description": "ID of a template folder on the target team to place the template in" } }, "required": [ "team_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/template" } } } } } } }, "/api/v1/admin/tunnel/{tunnel_name}/health": { "get": { "summary": "Retrieve tunnel health", "operationId": "get_api_v1_admin_tunnel_by_tunnel_name_health", "description": "Retrieve the health status of a tunnel. Requires a tenant-level API key.", "tags": [ "Admin > Tunnels" ], "parameters": [ { "name": "tunnel_name", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Name of the tunnel" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "health": { "type": "string", "description": "Health of the tunnel. One of: Down, Healthy, Inactive, Degraded" } } } } } } } } }, "/api/v1/admin/user_provisioning/mapping": { "post": { "summary": "Update the user provisioning mapping", "operationId": "post_api_v1_admin_user_provisioning_mapping", "description": "Update the user provisioning mapping for the tenant, mapping identity-provider groups to Tines teams, roles, and tenant permissions. The full user group mapping must be sent; appending a new mapping is not supported.", "tags": [ "Admin > User provisioning" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_group_mapping": { "$ref": "#/components/schemas/user_group_mapping" } }, "required": [ "user_group_mapping" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_group_mapping": { "$ref": "#/components/schemas/user_group_mapping" } } } } } }, "400": { "description": "A key in the mapping is not snake_case, such as tenantOwnersGroups instead of tenant_owners_groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The mapping uses the older sso_group key. Use group_name instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/admin/users": { "get": { "summary": "List users", "operationId": "get_api_v1_admin_users", "description": "Retrieve a list of users from the Tines tenant.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. Defaults to 20" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number. Defaults to 1" }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "TENANT_OWNER" ] }, "description": "Filter the returned users" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match against user name or email" }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "team_memberships" ] }, "description": "Include additional related data in the response" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "admin/users": { "type": "array", "items": { "$ref": "#/components/schemas/admin_user" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a user", "operationId": "post_api_v1_admin_users", "description": "Create a user in the Tines tenant.", "tags": [ "Admin > Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "User email" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" }, "admin": { "type": "boolean", "default": "false", "description": "Whether the user should be an admin" }, "tenant_permissions": { "type": "array", "items": { "type": "string" }, "description": "Tenant permission names to grant to the user" }, "is_active": { "type": "boolean", "default": "true", "description": "Whether the user should be active" }, "team_id": { "type": "integer", "description": "ID of a shared team to add the user to" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_user" } } } } } } }, "/api/v1/admin/users/{id}": { "get": { "summary": "Get a user", "operationId": "get_api_v1_admin_users_by_id", "description": "Retrieve details of a specific user by ID or email address.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID or email address of the user" }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "team_memberships" ] }, "description": "Include additional related data in the response" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_user" } } } } } }, "delete": { "summary": "Delete a user", "operationId": "delete_api_v1_admin_users_by_id", "description": "Delete a specific user from the Tines tenant.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the user" } ], "responses": { "204": { "description": "Empty response on success" } } }, "patch": { "summary": "Update a user", "operationId": "patch_api_v1_admin_users_by_id", "description": "Update a user in the Tines tenant.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the user" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "User email" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" }, "admin": { "type": "boolean", "description": "Whether the user should be an admin" }, "tenant_permissions": { "type": "array", "items": { "type": "string" }, "description": "Tenant permission names to grant to the user" }, "is_active": { "type": "boolean", "description": "Whether the user should be active" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_user" } } } } } }, "put": { "summary": "Update a user", "operationId": "put_api_v1_admin_users_by_id", "description": "Update a user in the Tines tenant.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the user" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "User email" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" }, "admin": { "type": "boolean", "description": "Whether the user should be an admin" }, "tenant_permissions": { "type": "array", "items": { "type": "string" }, "description": "Tenant permission names to grant to the user" }, "is_active": { "type": "boolean", "description": "Whether the user should be active" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_user" } } } } } } }, "/api/v1/admin/users/{user_id}/expire_session": { "post": { "summary": "Expire a user's session", "operationId": "post_api_v1_admin_users_by_user_id_expire_session", "description": "Expire a user's session, signing them out of the Tines tenant on all devices.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "user_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the user" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/admin/users/{user_id}/resend_invitation": { "post": { "summary": "Resend invitation", "operationId": "post_api_v1_admin_users_by_user_id_resend_invitation", "description": "Resend the platform invitation to the specified user.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "user_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the user to resend the invitation to" } ], "responses": { "200": { "description": "Empty response, or a message stating the user already accepted the invitation." } } } }, "/api/v1/admin/users/{user_id}/signin_activities": { "get": { "summary": "Get a user's sign-in activities", "operationId": "get_api_v1_admin_users_by_user_id_signin_activities", "description": "Retrieve a list of sign-in activities by a specified user. This endpoint returns a subset of the data available at the audit logs endpoint.", "tags": [ "Admin > Users" ], "parameters": [ { "name": "user_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the user" }, { "name": "before", "in": "query", "schema": { "type": "string" }, "description": "Only include sign-ins created before this timestamp" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Only include sign-ins created after this timestamp" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. Defaults to 20" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number. Defaults to 1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "admin/login_activities": { "type": "array", "items": { "$ref": "#/components/schemas/login_activity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/agents": { "get": { "summary": "List actions", "operationId": "get_api_v1_agents", "description": "Retrieve a list of actions available in the Tines tenant.", "tags": [ "Actions" ], "parameters": [ { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given story" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] }, "description": "List actions for the given story mode (must be used with story_id)" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given team" }, { "name": "group_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given group" }, { "name": "action_type", "in": "query", "schema": { "type": "string", "enum": [ "Agents::CaseAgent", "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::FormAgent", "Agents::GroupAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::RecordAgent", "Agents::RunScriptAgent", "Agents::SendToStoryAgent", "Agents::TriggerAgent", "Agents::WebhookAgent" ] }, "description": "Filter actions by the given type" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "List actions for the given draft" }, { "name": "include_live_activity", "in": "query", "schema": { "type": "boolean" }, "description": "When true, includes live activity metrics like pending_action_runs_count. Defaults to false." }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/story_action" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create an action", "operationId": "post_api_v1_agents", "description": "Create an action. Story or group ID must be provided. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided.", "tags": [ "Actions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Agents::EmailAgent", "Agents::EventTransformationAgent", "Agents::HTTPRequestAgent", "Agents::IMAPAgent", "Agents::LLMAgent", "Agents::TriggerAgent", "Agents::WebhookAgent", "Agents::SendToStoryAgent", "Agents::GroupAgent", "Agents::RunScriptAgent" ], "description": "Type of action to create" }, "name": { "type": "string", "description": "Name of the action" }, "options": { "type": "object", "description": "JSON options block of the action" }, "position": { "type": "object", "description": "An object describing the XY coordinates of the action on the story diagram" }, "story_id": { "type": "integer", "description": "ID of story to which the action should be added" }, "group_id": { "type": "integer", "description": "ID of group to which the action should be added" }, "description": { "type": "string", "description": "A user-defined description of the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled. Defaults to false." }, "source_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should receive emitted events from" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to source actions. Mutually exclusive with source_ids. Each object has source_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "receiver_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should emit events to" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids. Each object has receiver_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "schedule": { "type": "object", "description": "An object defining the cron schedule for the action" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails" }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored" }, "monitor_no_events_emitted": { "type": "integer", "description": "Duration in seconds. If no events are emitted in this time, a notification will be sent." }, "draft_id": { "type": "integer", "description": "ID of the draft to which the action should be added" } }, "required": [ "type", "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "The source or receiver link parameters are malformed, mutually exclusive, or contain an unsupported link type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{agent_id}/events": { "get": { "summary": "List events", "operationId": "get_api_v1_agents_by_agent_id_events", "description": "Retrieve a list of events. Also available nested under an action as /api/v1/actions/:agent_id/events. A response whose payloads exceed 200MB returns a 422 error.", "tags": [ "Events (v1)" ], "parameters": [ { "name": "agent_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the action whose events to retrieve" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the given team. When team_id and story_id are used together, story_id is ignored" }, { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the given story. When team_id and story_id are used together, story_id is ignored" }, { "name": "story_mode", "in": "query", "schema": { "type": "string" }, "description": "Set to test to retrieve events from the story's default test story. Only valid with story_id" }, { "name": "include_groups", "in": "query", "schema": { "type": "boolean" }, "description": "Include events from groups in the specified story. Only valid with story_id (defaults to false)" }, { "name": "since_id", "in": "query", "schema": { "type": "integer" }, "description": "Only retrieve events after this ID" }, { "name": "until_id", "in": "query", "schema": { "type": "integer" }, "description": "Only retrieve events until (and including) this ID" }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve events created after this time (ISO 8601 timestamp)" }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve events until this time (ISO 8601 timestamp)" }, { "name": "show_reemitted_events_only", "in": "query", "schema": { "type": "boolean" }, "description": "Only retrieve events that have been re-emitted (defaults to false)" }, { "name": "exclude_previous_event_payloads", "in": "query", "schema": { "type": "boolean" }, "description": "When true, each event's payload contains only its own output, excluding payloads received from upstream events (defaults to false)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20, maximum 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/event" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "The since or until parameter is not a valid date or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/EventPageTooLarge" } } } }, "/api/v1/agents/{id}": { "delete": { "summary": "Delete an action", "operationId": "delete_api_v1_agents_by_id", "description": "Delete a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an action", "operationId": "get_api_v1_agents_by_id", "description": "Retrieve details of a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" }, { "name": "include_live_activity", "in": "query", "schema": { "type": "boolean" }, "description": "When true, includes live activity metrics like pending_action_runs_count. Defaults to false." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } }, "patch": { "summary": "Update an action", "operationId": "patch_api_v1_agents_by_id", "description": "Update an action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action" }, "description": { "type": "string", "description": "A user-defined description of the action" }, "options": { "type": "object", "description": "JSON options block of the action" }, "position": { "type": "object", "description": "An object describing the XY coordinates of the action on the story diagram" }, "source_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should receive emitted events from" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to source actions. Mutually exclusive with source_ids. Each object has source_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "receiver_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should emit events to" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids. Each object has receiver_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "schedule": { "type": "object", "description": "An object defining the cron schedule for the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails. You must include monitor_all_events if updating this value." }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored. You must include monitor_failures if updating this value." }, "monitor_no_events_emitted": { "type": "integer", "description": "Duration in seconds. If no events are emitted in this time, a notification will be sent. You must include both monitor_failures and monitor_all_events if updating this value." }, "num_runs_to_save": { "type": "integer", "description": "Number of story runs to save for this action. Only applicable for Receive Email and Webhook actions." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "The source or receiver link parameters are invalid, or num_runs_to_save is used with an unsupported action type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an action", "operationId": "put_api_v1_agents_by_id", "description": "Update an action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the action" }, "description": { "type": "string", "description": "A user-defined description of the action" }, "options": { "type": "object", "description": "JSON options block of the action" }, "position": { "type": "object", "description": "An object describing the XY coordinates of the action on the story diagram" }, "source_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should receive emitted events from" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to source actions. Mutually exclusive with source_ids. Each object has source_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "receiver_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of action IDs the action should emit events to" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids. Each object has receiver_id (required) and type (optional; DEFAULT, NO_MATCH, or FAILURE)." }, "schedule": { "type": "object", "description": "An object defining the cron schedule for the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails. You must include monitor_all_events if updating this value." }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored. You must include monitor_failures if updating this value." }, "monitor_no_events_emitted": { "type": "integer", "description": "Duration in seconds. If no events are emitted in this time, a notification will be sent. You must include both monitor_failures and monitor_all_events if updating this value." }, "num_runs_to_save": { "type": "integer", "description": "Number of story runs to save for this action. Only applicable for Receive Email and Webhook actions." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "The source or receiver link parameters are invalid, or num_runs_to_save is used with an unsupported action type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{id}/clear_memory": { "delete": { "summary": "Clear an action's memory", "operationId": "delete_api_v1_agents_by_id_clear_memory", "description": "Clear all the values stored in an action's memory. Applicable for event transform actions in deduplicate or implode mode.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } } }, "/api/v1/agents/{id}/logs": { "get": { "summary": "List an action's logs", "operationId": "get_api_v1_agents_by_id_logs", "description": "List all logs emitted by a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" }, { "name": "level", "in": "query", "schema": { "type": "integer", "enum": [ 2, 3, 4 ] }, "description": "Filter logs by severity level (warning = 2, info = 3, error = 4). Pass a single value or multiple values." }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page. Defaults to 20." }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "action_logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Action log ID" }, "level": { "type": "integer", "description": "The severity level of the log (warning = 2, info = 3, error = 4)" }, "message": { "type": "string", "description": "The log message" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp representing creation date and time of the action log" }, "inbound_event": { "type": "object", "nullable": true, "description": "The inbound event for the action run" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/agents/{id}/remove_events": { "delete": { "summary": "Delete an action's events", "operationId": "delete_api_v1_agents_by_id_remove_events", "description": "Delete all events emitted by a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" }, { "name": "async_deletion", "in": "query", "schema": { "type": "boolean" }, "description": "Whether the deletion should be asynchronous by sending it to a background job" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } }, "400": { "description": "async_deletion is not true or false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/agents/{id}/remove_logs": { "delete": { "summary": "Delete an action's logs", "operationId": "delete_api_v1_agents_by_id_remove_logs", "description": "Delete all logs emitted by a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } } }, "/api/v1/agents/{id}/run": { "post": { "summary": "Run an action", "operationId": "post_api_v1_agents_by_id_run", "description": "Manually run a specific action.", "tags": [ "Actions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the action" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_action" } } } } } } }, "/api/v1/ai_providers": { "get": { "summary": "List AI providers", "operationId": "get_api_v1_ai_providers", "description": "Retrieve the AI providers and models available to the authenticated user. Admins receive all AI providers configured for the tenant. Non-admin users receive providers owned by one of their teams, shared with one of their teams, or available to the entire tenant. The response includes enabled and disabled providers.", "tags": [ "AI (v1)" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_providers": { "type": "array", "items": { "type": "object", "properties": { "guid": { "type": "string", "description": "Unique identifier of the AI provider" }, "enabled": { "type": "boolean", "description": "Whether the AI provider is enabled" }, "name": { "type": "string", "description": "The configured name of the AI provider, or its default provider name when no custom name is set" }, "provider_type": { "type": "string", "description": "Provider service. One of ANTHROPIC, OPEN_AI, AWS_BEDROCK, ORACLE_COHERE, MISTRAL, or GOOGLE_VERTEX" }, "provisioning_type": { "type": "string", "description": "How the provider is provisioned. One of customer_provisioned or tines_provisioned" }, "models": { "type": "array", "items": { "type": "object", "properties": { "display_name": { "type": "string", "description": "Human-readable name of the model" }, "api_model_id": { "type": "string", "description": "Identifier used to reference the model in the API" }, "description": { "type": "string", "nullable": true, "description": "Description of the model" }, "cost_tier": { "type": "string", "nullable": true, "description": "Relative cost of the model. One of LOW, MEDIUM, or HIGH" }, "legacy": { "type": "boolean", "description": "Whether the model is a legacy model" } } }, "description": "Array of models available through the provider" } } } } } } } } } } } }, "/api/v1/ai_usage": { "get": { "summary": "Get AI usage", "operationId": "get_api_v1_ai_usage", "description": "Retrieve aggregated AI usage for the tenant, including token counts, credits consumed, and cost in US dollars. Results can be filtered by time range, team, model, provider, feature, story, user, or action, and optionally grouped by one of these dimensions.\n\nAdmins see usage across the entire tenant. Non-admin users see usage from teams they belong to, plus usage rows not attributed to any team.\n\nSupply either relative_date or the start_date/end_date pair, not both.", "tags": [ "AI (v1)" ], "parameters": [ { "name": "relative_date", "in": "query", "schema": { "type": "string", "default": "30 days" }, "description": "Predefined time window relative to now, for example today, yesterday, 7 days, 30 days, 3 months, or 1 year. Defaults to 30 days. Cannot be combined with start_date and end_date" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "ISO 8601 timestamp for the start of a custom time window. Must be paired with end_date" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "ISO 8601 timestamp for the end of a custom time window. Must be paired with start_date, must be after start_date, and the window cannot exceed one year" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return usage attributed to the specified team. Non-admin users requesting usage for a team they don't belong to receive a zeroed response" }, { "name": "model_id", "in": "query", "schema": { "type": "string" }, "description": "Only return usage attributed to the specified model" }, { "name": "provider_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return usage attributed to the specified provider" }, { "name": "feature", "in": "query", "schema": { "type": "string", "enum": [ "workbench", "workbench_storyboard", "ai_agents", "workbench_cases", "workbench_apps", "other" ] }, "description": "Only return usage attributed to the specified feature" }, { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return runtime usage from AI actions and AI agents in the specified story. Non-admin users only see usage from teams they belong to, so requesting a story outside those teams returns a zeroed response" }, { "name": "user_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return usage initiated by the specified user. Non-admin users can only attribute usage to users they can see, so requesting any other user returns a zeroed response" }, { "name": "action_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return runtime usage from the specified AI action or AI agent. An AI action used as a tool by an agent reports its own usage under its own ID, not the agent's. Non-admin users only see usage from teams they belong to, so requesting an action outside those teams returns a zeroed response" }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "model", "provider", "team", "feature", "story", "user", "action", "day" ] }, "description": "Break the response into per-bucket groups along one dimension. When omitted, only the totals are returned" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "start": { "type": "string", "description": "ISO 8601 timestamp for the start of the window" }, "end": { "type": "string", "description": "ISO 8601 timestamp for the end of the window" } }, "description": "The resolved time window" }, "totals": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens consumed" }, "cached_read_input_tokens": { "type": "integer", "description": "Number of input tokens read from cache" }, "cached_write_input_tokens": { "type": "integer", "description": "Number of input tokens written to cache" }, "output_tokens": { "type": "integer", "description": "Number of output tokens generated" }, "credits_used": { "type": "integer", "description": "Number of credits consumed" }, "billed_cost": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code, for example USD" }, "amount": { "type": "string", "description": "Cost amount formatted to two decimal places" } }, "description": "Cost billed for the usage" }, "usage_count": { "type": "integer", "description": "Number of usage records aggregated into this bucket" } }, "description": "Aggregate usage across the entire window" }, "group_by": { "type": "string", "nullable": true, "description": "Echoes the group_by parameter when provided. Omitted when group_by is not set" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "input_tokens": { "type": "integer", "description": "Number of input tokens consumed" }, "cached_read_input_tokens": { "type": "integer", "description": "Number of input tokens read from cache" }, "cached_write_input_tokens": { "type": "integer", "description": "Number of input tokens written to cache" }, "output_tokens": { "type": "integer", "description": "Number of output tokens generated" }, "credits_used": { "type": "integer", "description": "Number of credits consumed" }, "billed_cost": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code, for example USD" }, "amount": { "type": "string", "description": "Cost amount formatted to two decimal places" } }, "description": "Cost billed for the usage" }, "usage_count": { "type": "integer", "description": "Number of usage records aggregated into this bucket" }, "model_id": { "type": "string", "nullable": true, "description": "Model identifier. Present when group_by is model" }, "provider_id": { "type": "integer", "nullable": true, "description": "Provider identifier. Present when group_by is provider" }, "provider_name": { "type": "string", "nullable": true, "description": "Provider name. Present when group_by is provider" }, "team_id": { "type": "integer", "nullable": true, "description": "Team identifier. Present when group_by is team. Usage in a user's personal space is attributed to their personal team. Null for operations that aren't scoped to a team, such as AI provider tests and background Workbench operations like conversation title generation, prompt suggestions, and tool selection. These operations report token usage but consume no credits" }, "team_name": { "type": "string", "nullable": true, "description": "Team name. Present when group_by is team. Personal teams are named after the user they belong to. Null whenever team_id is null" }, "story_id": { "type": "integer", "nullable": true, "description": "Story identifier. Present when group_by is story or action. Null for usage that didn't run inside a story, such as Workbench, or that came from a story the caller can't see" }, "story_name": { "type": "string", "nullable": true, "description": "Story name. Present when group_by is story. Null whenever story_id is null" }, "user_id": { "type": "integer", "nullable": true, "description": "User identifier. Present when group_by is user. Null for usage with no initiating user, such as AI actions and AI agents running in a story, and for usage initiated by a user the caller can't see" }, "user_email": { "type": "string", "nullable": true, "description": "User email. Present when group_by is user. Null whenever user_id is null and for service accounts" }, "user_name": { "type": "string", "nullable": true, "description": "User name. Present when group_by is user. Null whenever user_id is null" }, "is_service_account": { "type": "boolean", "nullable": true, "description": "Whether the user is a service account. Present when group_by is user. Null whenever user_id is null" }, "action_id": { "type": "integer", "nullable": true, "description": "Action identifier. Present when group_by is action. Null for usage that didn't come from an AI action or AI agent, or that came from an action the caller can't see" }, "action_name": { "type": "string", "nullable": true, "description": "Action name. Present when group_by is action. Null whenever action_id is null" }, "feature": { "type": "string", "nullable": true, "description": "Feature name. Present when group_by is feature. Usage that doesn't map to one of the listed features is collected under other, which covers story building helpers such as formula generation, automatic transforms, and action or story naming, along with AI provider tests" }, "day": { "type": "string", "nullable": true, "description": "ISO 8601 date. Present when group_by is day" } } }, "nullable": true, "description": "One usage bucket per grouping key. Omitted when group_by is not set" } } } } } }, "400": { "description": "The time window is invalid: relative_date was combined with start_date/end_date, only one of start_date and end_date was given, a timestamp could not be parsed, relative_date was not recognized, end_date was not after start_date, or the range exceeded one year. Also returned when feature is not a valid value, or when AI usage is not available on the tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/annotations": { "get": { "summary": "List notes", "operationId": "get_api_v1_annotations", "description": "List notes.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given story" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] }, "description": "List notes for the given story mode (must be used with story_id)" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given team" }, { "name": "group_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given group" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given draft" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/story_note" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a note", "operationId": "post_api_v1_annotations", "description": "Create a note on the storyboard. Story or Group ID must be provided. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided.", "tags": [ "Stories > Notes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "story_id": { "type": "integer", "description": "ID of the story to which the note should be added" }, "group_id": { "type": "integer", "description": "ID of the group to which the note should be added" }, "content": { "type": "string", "description": "The Markdown-formatted content of the note" }, "position": { "type": "object", "properties": { "x": { "type": "integer", "description": "The X coordinate" }, "y": { "type": "integer", "description": "The Y coordinate" } }, "description": "An object describing the XY coordinates of the position on the story diagram" }, "draft_id": { "type": "integer", "description": "ID of the draft to which the note should be added" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } } }, "/api/v1/annotations/{id}": { "delete": { "summary": "Delete a note", "operationId": "delete_api_v1_annotations_by_id", "description": "Delete a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the note to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a note", "operationId": "get_api_v1_annotations_by_id", "description": "Retrieve a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the note to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } }, "patch": { "summary": "Update a note", "operationId": "patch_api_v1_annotations_by_id", "description": "Update a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the note" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The Markdown-formatted content of the note" }, "position": { "type": "object", "properties": { "x": { "type": "integer", "description": "The X coordinate" }, "y": { "type": "integer", "description": "The Y coordinate" } }, "description": "An object describing the XY coordinates of the position on the story diagram" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } }, "put": { "summary": "Update a note", "operationId": "put_api_v1_annotations_by_id", "description": "Update a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the note" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The Markdown-formatted content of the note" }, "position": { "type": "object", "properties": { "x": { "type": "integer", "description": "The X coordinate" }, "y": { "type": "integer", "description": "The Y coordinate" } }, "description": "An object describing the XY coordinates of the position on the story diagram" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } } }, "/api/v1/apps": { "get": { "summary": "List apps", "operationId": "get_api_v1_apps", "description": "Retrieve a list of apps visible to the authenticated user.", "tags": [ "Apps (v1)" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Set the number of results returned per page. Defaults to 20." }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Specify the page of results to return if there are multiple pages. Defaults to page 1." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "$ref": "#/components/schemas/app" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Apps are not available on the tenant's plan, or the tenant has apps switched off. The body is [\"Not found\"], the same as for a URL that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an app", "operationId": "post_api_v1_apps", "description": "Create a new app.", "tags": [ "Apps (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The ID of the team the app belongs to." }, "name": { "type": "string", "description": "The app name." }, "description": { "type": "string", "description": "A user-defined description of the app." } }, "required": [ "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/apps/{id}": { "delete": { "summary": "Delete an app", "operationId": "delete_api_v1_apps_by_id", "description": "Delete an app and all of its versions.", "tags": [ "Apps (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the app to delete." } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an app", "operationId": "get_api_v1_apps_by_id", "description": "Retrieve a single app.", "tags": [ "Apps (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the app to retrieve." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app" } } } }, "404": { "description": "No app with that ID is visible to the API key, in which case the body is [\"App not found\"]; or apps are not available on the tenant's plan, or the tenant has apps switched off, in which case the body is [\"Not found\"].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/apps/{id}/files": { "put": { "summary": "Replace app files", "operationId": "put_api_v1_apps_by_id_files", "description": "Replace all draft files in an app. The request must include App.tsx.", "tags": [ "Apps (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the app whose draft files should be replaced." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The file path. One file must have the path App.tsx." }, "contents": { "type": "string", "description": "The file contents. Defaults to an empty string." } }, "required": [ "path" ] }, "description": "The complete set of draft files. Existing files omitted from this array are deleted." } }, "required": [ "files" ] }, "example": { "files": [ { "path": "App.tsx", "contents": "export default function App() { return

Hello

; }" } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The file path." }, "contents": { "type": "string", "description": "The file contents." } } }, "description": "The app's complete set of draft files." } } }, "example": { "files": [ { "path": "App.tsx", "contents": "export default function App() { return

Hello

; }" } ] } } } } } } }, "/api/v1/apps/{id}/publish": { "post": { "summary": "Publish an app", "operationId": "post_api_v1_apps_by_id_publish", "description": "Publish the app's current draft as a new version. If the draft is unchanged since the latest version, that version is published instead.", "tags": [ "Apps (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the app to publish." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name for the published version." }, "description": { "type": "string", "description": "A description of the published version." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app" } } } } } } }, "/api/v1/audit_logs": { "get": { "summary": "List audit logs", "operationId": "get_api_v1_audit_logs", "description": "Returns a list of audit logs gathered from the Tines tenant. Each entry records a user operation executed on the database along with its inputs, outputs, and the user who triggered it.", "tags": [ "Audit Logs" ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "string" }, "description": "Only include logs created before this ISO 8601 timestamp" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Only include logs created after this ISO 8601 timestamp" }, { "name": "user_id[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Only include logs from matching users. Repeat as user_id[]= to select multiple users, e.g. ?user_id[]=1&user_id[]=2" }, { "name": "operation_name[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Only include logs with matching operation names. Repeat as operation_name[]= to select multiple, e.g. ?operation_name[]=StoryItemsMovement&operation_name[]=StoryItemsCreation" }, { "name": "team_id[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Only include logs from matching teams. Repeat as team_id[]= to select multiple teams, e.g. ?team_id[]=1&team_id[]=2" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": "20" }, "description": "Number of results returned per page" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": "1" }, "description": "Page of results to return" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "audit_logs": { "type": "array", "items": { "$ref": "#/components/schemas/audit_log" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/dashboards": { "get": { "summary": "List dashboards", "operationId": "get_api_v1_dashboards", "tags": [ "Records > Dashboards" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return dashboards belonging to this team" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "NAME", "RECENTLY_EDITED", "LEAST_RECENTLY_EDITED", "CREATED_DESC", "CREATED_ASC" ] }, "description": "Order the results (defaults to NAME)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20, maximum 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "dashboards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the dashboard" }, "name": { "type": "string", "description": "Name of the dashboard" }, "team": { "type": "object", "description": "The team this dashboard belongs to, with its id and name" }, "created_at": { "type": "string", "description": "When the dashboard was created" }, "updated_at": { "type": "string", "description": "When the dashboard was last updated" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/dashboards/{id}": { "delete": { "summary": "Delete a dashboard", "operationId": "delete_api_v1_dashboards_by_id", "tags": [ "Records > Dashboards" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the dashboard to delete" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/dashboards/{id}/export": { "get": { "summary": "Export a dashboard", "operationId": "get_api_v1_dashboards_by_id_export", "description": "Export a dashboard as JSON that can be passed to the import endpoint.", "tags": [ "Records > Dashboards" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the dashboard to export" } ], "responses": { "200": { "description": "The dashboard in exported JSON form" } } } }, "/api/v1/dashboards/import": { "post": { "summary": "Import a dashboard", "operationId": "post_api_v1_dashboards_import", "description": "Import a dashboard from data obtained from the export endpoint.", "tags": [ "Records > Dashboards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "ID of the team to add the dashboard to" }, "data": { "type": "object", "description": "The dashboard in exported form" }, "mode": { "type": "string", "enum": [ "new", "replace" ], "description": "Create a new dashboard or replace an existing one by name (defaults to new)" }, "new_name": { "type": "string", "description": "Name for the dashboard. In replace mode, selects which existing dashboard to replace" } }, "required": [ "team_id", "data" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the dashboard" }, "name": { "type": "string", "description": "Name of the dashboard" }, "team": { "type": "object", "description": "The team this dashboard belongs to, with its id and name" }, "created_at": { "type": "string", "description": "When the dashboard was created" }, "updated_at": { "type": "string", "description": "When the dashboard was last updated" } } } } } }, "400": { "description": "The import data is not a JSON object, cannot be parsed, or contains an invalid team identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/events": { "get": { "summary": "List events", "operationId": "get_api_v1_events", "description": "Retrieve a list of events. Also available nested under an action as /api/v1/actions/:agent_id/events. A response whose payloads exceed 200MB returns a 422 error.", "tags": [ "Events (v1)" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the given team. When team_id and story_id are used together, story_id is ignored" }, { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the given story. When team_id and story_id are used together, story_id is ignored" }, { "name": "story_mode", "in": "query", "schema": { "type": "string" }, "description": "Set to test to retrieve events from the story's default test story. Only valid with story_id" }, { "name": "include_groups", "in": "query", "schema": { "type": "boolean" }, "description": "Include events from groups in the specified story. Only valid with story_id (defaults to false)" }, { "name": "since_id", "in": "query", "schema": { "type": "integer" }, "description": "Only retrieve events after this ID" }, { "name": "until_id", "in": "query", "schema": { "type": "integer" }, "description": "Only retrieve events until (and including) this ID" }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve events created after this time (ISO 8601 timestamp)" }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve events until this time (ISO 8601 timestamp)" }, { "name": "show_reemitted_events_only", "in": "query", "schema": { "type": "boolean" }, "description": "Only retrieve events that have been re-emitted (defaults to false)" }, { "name": "exclude_previous_event_payloads", "in": "query", "schema": { "type": "boolean" }, "description": "When true, each event's payload contains only its own output, excluding payloads received from upstream events (defaults to false)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20, maximum 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/event" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "The since or until parameter is not a valid date or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/EventPageTooLarge" } } } }, "/api/v1/events/{id}": { "get": { "summary": "Get an event", "operationId": "get_api_v1_events_by_id", "tags": [ "Events (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the event to retrieve" }, { "name": "exclude_previous_event_payloads", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the payload field contains only this event's own output, excluding payloads received from upstream events (defaults to false)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event" } } } } } } }, "/api/v1/events/{id}/reemit": { "post": { "summary": "Re-emit an event", "operationId": "post_api_v1_events_by_id_reemit", "tags": [ "Events (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the event to re-emit" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/folders": { "get": { "summary": "List folders", "operationId": "get_api_v1_folders", "tags": [ "Folders (v1)" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "ID of team to which the folders belong" }, { "name": "content_type", "in": "query", "schema": { "type": "string", "enum": [ "CREDENTIAL", "RESOURCE", "STORY" ] }, "description": "The type of content stored in the folders" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "folders": { "type": "array", "items": { "$ref": "#/components/schemas/folder" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a folder", "operationId": "post_api_v1_folders", "tags": [ "Folders (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The folder name" }, "content_type": { "type": "string", "enum": [ "CREDENTIAL", "RESOURCE", "STORY" ], "description": "The type of content stored in this folder" }, "team_id": { "type": "integer", "description": "ID of team the folder should be created in" }, "parent_folder_id": { "type": "integer", "description": "ID of the parent folder (defaults to null, the root level)" } }, "required": [ "name", "content_type", "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/folder" } } } } } } }, "/api/v1/folders/{id}": { "delete": { "summary": "Delete a folder", "operationId": "delete_api_v1_folders_by_id", "tags": [ "Folders (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the folder to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a folder", "operationId": "get_api_v1_folders_by_id", "tags": [ "Folders (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the folder to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/folder" } } } } } }, "patch": { "summary": "Update a folder", "operationId": "patch_api_v1_folders_by_id", "tags": [ "Folders (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the folder to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The folder name" }, "parent_folder_id": { "type": "integer", "description": "ID of the parent folder. Set to an empty value to move to the root level" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/folder" } } } } } }, "put": { "summary": "Update a folder", "operationId": "put_api_v1_folders_by_id", "tags": [ "Folders (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the folder to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The folder name" }, "parent_folder_id": { "type": "integer", "description": "ID of the parent folder. Set to an empty value to move to the root level" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/folder" } } } } } } }, "/api/v1/global_resources": { "get": { "summary": "List resources", "operationId": "get_api_v1_global_resources", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Return resources belonging to this team" }, { "name": "folder_id", "in": "query", "schema": { "type": "integer" }, "description": "Return resources in this folder" }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "UNUSED_IN_ACTIONS" ] }, "description": "Filter resources" }, { "name": "include_referencing_action_ids", "in": "query", "schema": { "type": "boolean" }, "description": "Defaults to true. When false, referencing_action_ids is excluded from the response" }, { "name": "typed_value", "in": "query", "schema": { "type": "boolean" }, "description": "Defaults to false. When true, returns properly typed values (boolean, number, array, object) instead of strings" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "global_resources": { "type": "array", "items": { "$ref": "#/components/schemas/global_resource" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a resource", "operationId": "post_api_v1_global_resources", "description": "For a test resource used in TEST mode of change control, provide live_resource_id; the other optional values then default to those of the specified live resource.", "tags": [ "Global resources (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the resource" }, "value": { "type": "string", "description": "Contents of the resource. A non-JSON string is parsed as regular text; pass a JSON object or array for a JSON resource" }, "team_id": { "type": "integer", "description": "ID of the team where the resource will be located" }, "folder_id": { "type": "integer", "description": "ID of the folder where the resource will be located" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this resource can be used (defaults to TEAM). SPECIFIC_TEAMS is a premium feature" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this resource can be used. Required to set read_access to SPECIFIC_TEAMS (defaults to [])" }, "description": { "type": "string", "description": "Description of the resource (defaults to \"\")" }, "live_resource_id": { "type": "integer", "description": "ID of the live resource that this new test value corresponds to" }, "include_referencing_action_ids": { "type": "boolean", "description": "Defaults to true. When false, referencing_action_ids is excluded from the response" }, "typed_value": { "type": "boolean", "description": "Defaults to false. When true, returns properly typed values (boolean, number, array, object) instead of strings" } }, "required": [ "name", "value", "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/global_resource" } } } }, "400": { "description": "team_id is missing and no default team can be selected for the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/global_resources/{id}": { "delete": { "summary": "Delete a resource", "operationId": "delete_api_v1_global_resources_by_id", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a resource", "operationId": "get_api_v1_global_resources_by_id", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource to retrieve" }, { "name": "include_referencing_action_ids", "in": "query", "schema": { "type": "boolean" }, "description": "Defaults to true. When false, referencing_action_ids is excluded from the response" }, { "name": "typed_value", "in": "query", "schema": { "type": "boolean" }, "description": "Defaults to false. When true, returns properly typed values (boolean, number, array, object) instead of strings" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/global_resource" } } } } } }, "patch": { "summary": "Update a resource", "operationId": "patch_api_v1_global_resources_by_id", "description": "Update a resource. If the resource has a test value it can be modified using the is_test parameter.", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Contents of the resource. For file resources, pass a JSON object with name, contents (base64), and optional type" }, "name": { "type": "string", "description": "Name of the resource" }, "folder_id": { "type": "integer", "description": "ID of the folder to move the resource to, or an empty value for the root folder" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this resource can be used (defaults to TEAM). SPECIFIC_TEAMS is a premium feature" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this resource can be used. Required to set read_access to SPECIFIC_TEAMS (defaults to [])" }, "description": { "type": "string", "description": "Description of the resource (defaults to \"\")" }, "test_resource_enabled": { "type": "boolean", "description": "Whether the resource is enabled for using a test resource" }, "is_test": { "type": "boolean", "description": "Whether the test resource should be updated. Requires test_resource_enabled true and an existing test resource" }, "include_referencing_action_ids": { "type": "boolean", "description": "Defaults to true. When false, referencing_action_ids is excluded from the response" }, "typed_value": { "type": "boolean", "description": "Defaults to false. When true, returns properly typed values (boolean, number, array, object) instead of strings" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/global_resource" } } } } } }, "put": { "summary": "Update a resource", "operationId": "put_api_v1_global_resources_by_id", "description": "Update a resource. If the resource has a test value it can be modified using the is_test parameter.", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Contents of the resource. For file resources, pass a JSON object with name, contents (base64), and optional type" }, "name": { "type": "string", "description": "Name of the resource" }, "folder_id": { "type": "integer", "description": "ID of the folder to move the resource to, or an empty value for the root folder" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this resource can be used (defaults to TEAM). SPECIFIC_TEAMS is a premium feature" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this resource can be used. Required to set read_access to SPECIFIC_TEAMS (defaults to [])" }, "description": { "type": "string", "description": "Description of the resource (defaults to \"\")" }, "test_resource_enabled": { "type": "boolean", "description": "Whether the resource is enabled for using a test resource" }, "is_test": { "type": "boolean", "description": "Whether the test resource should be updated. Requires test_resource_enabled true and an existing test resource" }, "include_referencing_action_ids": { "type": "boolean", "description": "Defaults to true. When false, referencing_action_ids is excluded from the response" }, "typed_value": { "type": "boolean", "description": "Defaults to false. When true, returns properly typed values (boolean, number, array, object) instead of strings" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/global_resource" } } } } } } }, "/api/v1/global_resources/{id}/append": { "post": { "summary": "Append an element to a resource", "operationId": "post_api_v1_global_resources_by_id_append", "description": "Append a string or an array to a resource. If the resource has a test value it can be modified using the is_test parameter.", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The string or array to append to the resource" }, "is_test": { "type": "boolean", "description": "Whether the test resource should be used" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "The updated resource value" } } } }, "/api/v1/global_resources/{id}/locked": { "put": { "summary": "Lock or unlock a resource", "operationId": "put_api_v1_global_resources_by_id_locked", "description": "Lock or unlock a resource. Locking prevents its value from being modified. Requires the RESOURCE_MANAGE permission. Unlocking via the API is permanent. Locking or unlocking also applies to the resource's test resource.", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the resource" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locked": { "type": "boolean", "description": "true to lock the resource, false to unlock" } }, "required": [ "locked" ] } } } }, "responses": { "200": { "description": "The resource's id and locked status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Resource ID" }, "locked": { "type": "boolean", "description": "Whether the resource is locked" } } } } } } } } }, "/api/v1/global_resources/{id}/remove": { "post": { "summary": "Remove an element from a resource", "operationId": "post_api_v1_global_resources_by_id_remove", "description": "Remove a top-level element from an array or a key from an object in a resource. Returns the removed item. If the resource has a test value it can be modified using the is_test parameter.", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The object key to remove if removing from an object" }, "index": { "type": "integer", "description": "The array index to remove (starting at 0). If omitted, the last element is removed" }, "if_value": { "type": "string", "description": "When provided, only proceeds if the current value at the key or index matches; otherwise a 422 with the current value is returned. A null value is treated as omitting the parameter" }, "is_test": { "type": "boolean", "description": "Whether the test resource should be used" } } } } } }, "responses": { "200": { "description": "The removed item from the resource" }, "422": { "$ref": "#/components/responses/ConditionalMismatch" } } } }, "/api/v1/global_resources/{id}/replace": { "post": { "summary": "Replace an element in a resource", "operationId": "post_api_v1_global_resources_by_id_replace", "description": "Replace a top-level element in an array or a key in an object in a resource. Returns the updated resource value. If the resource has a test value it can be modified using the is_test parameter.", "tags": [ "Global resources (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the live resource" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "The object key to replace if replacing in an object" }, "index": { "type": "integer", "description": "The array index to replace (starting at 0)" }, "value": { "type": "string", "description": "The new value to replace the existing element with" }, "if_value": { "type": "string", "description": "When provided, only proceeds if the current value at the key or index matches; otherwise a 422 with the current value is returned. A null value is treated as omitting the parameter" }, "is_test": { "type": "boolean", "description": "Whether the test resource should be used" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "The updated resource value" }, "422": { "$ref": "#/components/responses/ConditionalMismatch" } } } }, "/api/v1/groups/{id}/runs": { "get": { "summary": "List group runs", "operationId": "get_api_v1_groups_by_id_runs", "description": "Retrieve a list of group runs.", "tags": [ "Stories > Groups" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the group" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "group_runs": { "type": "array", "items": { "$ref": "#/components/schemas/story_run" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/groups/{id}/runs/{group_run_guid}": { "get": { "summary": "List group run events", "operationId": "get_api_v1_groups_by_id_runs_by_group_run_guid", "description": "Retrieve a list of events for a group run.", "tags": [ "Stories > Groups" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the group" }, { "name": "group_run_guid", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The guid of the group run" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "A list of events for the group run", "content": { "application/json": { "schema": { "type": "object", "properties": { "group_run_events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID of the event" }, "action_id": { "type": "integer", "description": "ID of the action that emitted the event" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp representing the date and time the event was emitted" }, "is_reemitted": { "type": "boolean", "description": "Whether this event has been re-emitted" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/info": { "get": { "summary": "Get tenant stack information", "operationId": "get_api_v1_info", "description": "Retrieve basic information regarding your tenant's stack.", "tags": [ "Info" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/info" } } } } } } }, "/api/v1/info/web_stats": { "get": { "summary": "Get web server statistics", "operationId": "get_api_v1_info_web_stats", "description": "Retrieve operational information about your web server. If you are running multiple tines-web containers then this will only reflect the stats for the container that handled this request. If you are using a load balancer this would be an arbitrary container unless you made the request from within the container's network. This endpoint is accessible only to self-hosted customers.", "tags": [ "Info" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web_stats" } } } }, "422": { "description": "The tenant is Tines-hosted, where web server stats are not available. The body is an empty object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObjectError" } } } } } } }, "/api/v1/info/worker_stats": { "get": { "summary": "Get worker statistics", "operationId": "get_api_v1_info_worker_stats", "description": "Retrieve essential information about worker statistics. This endpoint is accessible only to self-hosted customers.", "tags": [ "Info" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/worker_stats" } } } } } } }, "/api/v1/links": { "delete": { "summary": "Delete links", "operationId": "delete_api_v1_links", "description": "Delete one or more links between actions. All links must belong to the same story.", "tags": [ "Stories > Links" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "integer", "description": "The ID of the source action" }, "receiver_id": { "type": "integer", "description": "The ID of the receiver action" } }, "required": [ "source_id", "receiver_id" ] }, "description": "An array of link objects to delete. Each object must include source_id and receiver_id." } }, "required": [ "links" ] } } } }, "responses": { "204": { "description": "Empty response on success" }, "400": { "description": "links is not an array of objects, an entry is missing source_id or receiver_id, or the links do not all belong to the same story. Every link is resolved before any is deleted, so a rejected request deletes nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "One of the requested links does not exist, or is not visible to the API key. No links are deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notes": { "get": { "summary": "List notes", "operationId": "get_api_v1_notes", "description": "List notes.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given story" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "LIVE", "TEST" ] }, "description": "List notes for the given story mode (must be used with story_id)" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given team" }, { "name": "group_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given group" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "List notes for the given draft" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/story_note" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a note", "operationId": "post_api_v1_notes", "description": "Create a note on the storyboard. Story or Group ID must be provided. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided.", "tags": [ "Stories > Notes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "story_id": { "type": "integer", "description": "ID of the story to which the note should be added" }, "group_id": { "type": "integer", "description": "ID of the group to which the note should be added" }, "content": { "type": "string", "description": "The Markdown-formatted content of the note" }, "position": { "type": "object", "properties": { "x": { "type": "integer", "description": "The X coordinate" }, "y": { "type": "integer", "description": "The Y coordinate" } }, "description": "An object describing the XY coordinates of the position on the story diagram" }, "draft_id": { "type": "integer", "description": "ID of the draft to which the note should be added" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } } }, "/api/v1/notes/{id}": { "delete": { "summary": "Delete a note", "operationId": "delete_api_v1_notes_by_id", "description": "Delete a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the note to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a note", "operationId": "get_api_v1_notes_by_id", "description": "Retrieve a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the note to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } }, "patch": { "summary": "Update a note", "operationId": "patch_api_v1_notes_by_id", "description": "Update a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the note" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The Markdown-formatted content of the note" }, "position": { "type": "object", "properties": { "x": { "type": "integer", "description": "The X coordinate" }, "y": { "type": "integer", "description": "The Y coordinate" } }, "description": "An object describing the XY coordinates of the position on the story diagram" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } }, "put": { "summary": "Update a note", "operationId": "put_api_v1_notes_by_id", "description": "Update a note.", "tags": [ "Stories > Notes" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the note" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "The Markdown-formatted content of the note" }, "position": { "type": "object", "properties": { "x": { "type": "integer", "description": "The X coordinate" }, "y": { "type": "integer", "description": "The Y coordinate" } }, "description": "An object describing the XY coordinates of the position on the story diagram" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_note" } } } } } } }, "/api/v1/record_types": { "get": { "summary": "List record types", "operationId": "get_api_v1_record_types", "tags": [ "Records > Record Types" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "ID of the team the record types belong to" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "record_types": { "type": "array", "items": { "$ref": "#/components/schemas/record_type" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a record type", "operationId": "post_api_v1_record_types", "tags": [ "Records > Record Types" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The record type name" }, "team_id": { "type": "integer", "description": "ID of the team the record type belongs to" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The field name" }, "result_type": { "type": "string", "enum": [ "TEXT", "NUMBER", "BOOLEAN", "TIMESTAMP", "TEXT_ENUM", "ARTIFACT", "JSON", "TEXT_REGEX", "EMAIL", "URL", "IP_ADDRESS" ], "description": "The field's data type" }, "fixed_values": { "type": "array", "items": { "type": "string" }, "description": "Allowed values, required for TEXT_ENUM fields (max 100 entries)" }, "description": { "type": "string", "description": "A short description of the field" }, "config": { "type": "object", "description": "Field configuration, including regex for TEXT_REGEX fields and disable_hyperlink for URL fields. Replaces existing configuration when supplied" } }, "required": [ "name", "result_type" ] }, "description": "The custom record fields to create (at most 50 per record type)" }, "description": { "type": "string", "description": "A short description of the record type" }, "editable": { "type": "boolean", "description": "Whether records for this record type are editable" }, "ttl_days": { "type": "number", "description": "Records of this type are deleted after this number of days" }, "retention_column_name": { "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT" ], "description": "Timestamp column used for TTL expiry (defaults to CREATED_AT). Stored even when ttl_days is unset and used once a TTL is enabled; an invalid value returns a 400" }, "on_limit_reached": { "type": "string", "enum": [ "REJECT", "EVICT_OLDEST" ], "description": "Behavior when the per-type record limit is reached (defaults to REJECT)" }, "max_records_limit": { "type": "integer", "description": "Custom per-record-type record limit. Omit to use the tenant default" } }, "required": [ "name", "team_id", "fields" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_type" } } } }, "400": { "description": "A field definition, retention setting, limit, or limit behavior is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/record_types/{id}": { "delete": { "summary": "Delete a record type", "operationId": "delete_api_v1_record_types_by_id", "description": "Also deletes all records of this type, their artifacts, and record views built on it.", "tags": [ "Records > Record Types" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record type to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a record type", "operationId": "get_api_v1_record_types_by_id", "tags": [ "Records > Record Types" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record type to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_type" } } } } } }, "patch": { "summary": "Update a record type", "operationId": "patch_api_v1_record_types_by_id", "tags": [ "Records > Record Types" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record type to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The record type name" }, "description": { "type": "string", "description": "A short description of the record type" }, "editable": { "type": "boolean", "description": "Whether records for this record type are editable" }, "ttl_days": { "type": "number", "description": "Records of this type are deleted after this number of days" }, "retention_column_name": { "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT" ], "description": "Timestamp column used for TTL expiry. Stored even when ttl_days is unset and used once a TTL is enabled; an invalid value returns a 400 and a blank value leaves it unchanged" }, "on_limit_reached": { "type": "string", "enum": [ "REJECT", "EVICT_OLDEST" ], "description": "Behavior when the per-type record limit is reached" }, "max_records_limit": { "type": "integer", "description": "Custom per-record-type record limit. Send null to clear an existing custom limit" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Required to update an existing field; omit to create a new one" }, "name": { "type": "string", "description": "The field name" }, "result_type": { "type": "string", "enum": [ "TEXT", "NUMBER", "BOOLEAN", "TIMESTAMP", "TEXT_ENUM", "ARTIFACT", "JSON", "TEXT_REGEX", "EMAIL", "URL", "IP_ADDRESS" ], "description": "The field's data type" }, "fixed_values": { "type": "array", "items": { "type": "string" }, "description": "Allowed values, required for TEXT_ENUM fields (max 100 entries)" }, "description": { "type": "string", "description": "A short description of the field" }, "config": { "type": "object", "description": "Field configuration, including regex for TEXT_REGEX fields and disable_hyperlink for URL fields. Replaces existing configuration when supplied" } } }, "description": "Fields to create or update. Fields not included are preserved unchanged" }, "field_ids_to_delete": { "type": "array", "items": { "type": "integer" }, "description": "Field IDs to delete. Built-in default fields cannot be deleted" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_type" } } } }, "400": { "description": "A field update or deletion, retention setting, limit, or limit behavior is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a record type", "operationId": "put_api_v1_record_types_by_id", "tags": [ "Records > Record Types" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record type to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The record type name" }, "description": { "type": "string", "description": "A short description of the record type" }, "editable": { "type": "boolean", "description": "Whether records for this record type are editable" }, "ttl_days": { "type": "number", "description": "Records of this type are deleted after this number of days" }, "retention_column_name": { "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT" ], "description": "Timestamp column used for TTL expiry. Stored even when ttl_days is unset and used once a TTL is enabled; an invalid value returns a 400 and a blank value leaves it unchanged" }, "on_limit_reached": { "type": "string", "enum": [ "REJECT", "EVICT_OLDEST" ], "description": "Behavior when the per-type record limit is reached" }, "max_records_limit": { "type": "integer", "description": "Custom per-record-type record limit. Send null to clear an existing custom limit" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Required to update an existing field; omit to create a new one" }, "name": { "type": "string", "description": "The field name" }, "result_type": { "type": "string", "enum": [ "TEXT", "NUMBER", "BOOLEAN", "TIMESTAMP", "TEXT_ENUM", "ARTIFACT", "JSON", "TEXT_REGEX", "EMAIL", "URL", "IP_ADDRESS" ], "description": "The field's data type" }, "fixed_values": { "type": "array", "items": { "type": "string" }, "description": "Allowed values, required for TEXT_ENUM fields (max 100 entries)" }, "description": { "type": "string", "description": "A short description of the field" }, "config": { "type": "object", "description": "Field configuration, including regex for TEXT_REGEX fields and disable_hyperlink for URL fields. Replaces existing configuration when supplied" } } }, "description": "Fields to create or update. Fields not included are preserved unchanged" }, "field_ids_to_delete": { "type": "array", "items": { "type": "integer" }, "description": "Field IDs to delete. Built-in default fields cannot be deleted" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_type" } } } }, "400": { "description": "A field update or deletion, retention setting, limit, or limit behavior is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/record_views": { "get": { "summary": "List record views", "operationId": "get_api_v1_record_views", "tags": [ "Records > Record Views" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return record views belonging to this team" }, { "name": "record_type_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return record views for this record type" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "NAME", "RECENTLY_CREATED", "RECENTLY_UPDATED" ] }, "description": "Order the results (defaults to NAME)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20, maximum 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "record_views": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the record view" }, "name": { "type": "string", "description": "Name of the record view" }, "team": { "type": "object", "description": "The team this record view belongs to, with its id and name" }, "record_type": { "type": "object", "description": "The record type used by this record view, with its id and name" }, "created_at": { "type": "string", "description": "When the record view was created" }, "updated_at": { "type": "string", "description": "When the record view was last updated" }, "report_view": { "type": "string", "description": "The default view: record_table, split_view, or chart" }, "url": { "type": "string", "description": "Relative URL path to access the record view" }, "record_report_group_id": { "type": "integer", "description": "ID of the record report group this view belongs to" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/record_views/{id}": { "delete": { "summary": "Delete a record view", "operationId": "delete_api_v1_record_views_by_id", "tags": [ "Records > Record Views" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record view to delete" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/record_views/{id}/export": { "get": { "summary": "Export a record view", "operationId": "get_api_v1_record_views_by_id_export", "description": "Export a record view as JSON that can be passed to the import endpoint.", "tags": [ "Records > Record Views" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record view to export" } ], "responses": { "200": { "description": "The record view in exported JSON form" } } } }, "/api/v1/record_views/import": { "post": { "summary": "Import a record view", "operationId": "post_api_v1_record_views_import", "description": "Import a record view from data obtained from the export endpoint.", "tags": [ "Records > Record Views" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "ID of the team to add the record view to" }, "data": { "type": "object", "description": "The record view in exported form" }, "mode": { "type": "string", "enum": [ "new", "replace" ], "description": "Create a new record view or replace an existing one by name (defaults to new)" }, "name": { "type": "string", "description": "Name for the record view. In replace mode, selects which existing view to replace" } }, "required": [ "team_id", "data" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the record view" }, "name": { "type": "string", "description": "Name of the record view" }, "team": { "type": "object", "description": "The team this record view belongs to, with its id and name" }, "created_at": { "type": "string", "description": "When the record view was created" }, "updated_at": { "type": "string", "description": "When the record view was last updated" } } } } } }, "400": { "description": "The import data is not a JSON object, cannot be parsed, or contains an invalid team identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/records": { "get": { "summary": "List records", "operationId": "get_api_v1_records", "description": "Retrieve a list of records. For aggregates, use the Query records endpoint instead.", "tags": [ "Records" ], "parameters": [ { "name": "record_type_id", "in": "query", "schema": { "type": "integer" }, "description": "The ID of the record type (optional if record_field_ids are present)" }, { "name": "record_field_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Record field IDs determining which fields are returned (optional if record_type_id is present)" }, { "name": "range_start", "in": "query", "schema": { "type": "string" }, "description": "Start of the record time range (ISO 8601 timestamp)" }, { "name": "range_end", "in": "query", "schema": { "type": "string" }, "description": "End of the record time range (ISO 8601 timestamp)" }, { "name": "story_container_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Story IDs to filter the results. Cannot be used with story_ids" }, { "name": "order_direction", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "description": "Direction to order records (defaults to DESC)" }, { "name": "order_field_id", "in": "query", "schema": { "type": "integer" }, "description": "ID of the field used to order records. Defaults to creation date" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of records per page (defaults to 20, maximum 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" }, { "name": "filters", "in": "query", "schema": { "type": "string" }, "description": "A JSON-array string of filter objects, each with field_id, operator, and value" }, { "name": "test_mode", "in": "query", "schema": { "type": "string" }, "description": "Set to \"true\" to filter by records created in test stories (defaults to false)" }, { "name": "parent_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Parent record IDs (max 100). Returns only first-degree child records of those parents" }, { "name": "story_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Deprecated. Internal story IDs to filter the results. Cannot be used with story_container_ids\n\n**Deprecated. Use story_container_ids instead.**", "deprecated": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "record_results": { "type": "array", "items": { "$ref": "#/components/schemas/record_result_v1" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "record_type": { "type": "object", "description": "The record type, with its id and name" } } } } } }, "400": { "description": "A pagination, date range, record type, record field, or filter parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a record", "operationId": "post_api_v1_records", "tags": [ "Records" ], "parameters": [ { "name": "resolve_artifacts", "in": "query", "schema": { "type": "string" }, "description": "Set to \"false\" to return Artifacts (large text) fields as an artifact-ID reference instead of the full contents" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_type_id": { "type": "integer", "description": "ID of the record type to create the record for" }, "field_values": { "type": "array", "items": { "type": "object" }, "description": "An array of { field_id, value } objects assigning data to each record field" }, "case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Case IDs to link to this record (at most 5)" }, "parent_record_id": { "type": "integer", "description": "The ID of the record to link as this record's parent" }, "test_mode": { "type": "boolean", "description": "Set to true to create the record in test mode (defaults to false)" } }, "required": [ "record_type_id", "field_values" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_v1" } } } } } } }, "/api/v1/records/{id}": { "delete": { "summary": "Delete a record", "operationId": "delete_api_v1_records_by_id", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a record", "operationId": "get_api_v1_records_by_id", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record to retrieve" }, { "name": "record_type_id", "in": "query", "schema": { "type": "integer" }, "description": "Scope the lookup to this record type for a faster query" }, { "name": "record_field_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Only include the specified fields. id, updated_at, and case_ids are always returned" }, { "name": "resolve_artifacts", "in": "query", "schema": { "type": "string" }, "description": "Set to \"true\" to return full Artifacts (large text) contents instead of the artifact ID (defaults to false)" }, { "name": "include_children", "in": "query", "schema": { "type": "string" }, "description": "Set to \"true\" for full child record data, \"false\" to omit children. Defaults to child record IDs only" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_v1" } } } } } }, "patch": { "summary": "Update a record", "operationId": "patch_api_v1_records_by_id", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record to update" }, { "name": "resolve_artifacts", "in": "query", "schema": { "type": "string" }, "description": "Set to \"false\" to return Artifacts (large text) fields as an artifact-ID reference instead of the full contents" }, { "name": "include_children", "in": "query", "schema": { "type": "string" }, "description": "Set to \"false\" to omit child records from the response. Defaults to including full child field data" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "field_values": { "type": "array", "items": { "type": "object" }, "description": "An array of { field_id, value } objects. Only works if the record type is editable" }, "add_child_records": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to add as child records" }, "remove_child_records": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to remove as child records" }, "parent_record_id": { "type": "integer", "description": "Record ID to link as the parent. Send null to remove the parent, omit to leave unchanged" }, "add_case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Case IDs to link to the record (at most 5)" }, "remove_case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Case IDs to unlink from the record (at most 5)" }, "test_mode": { "type": "boolean", "description": "Set to true to only update a test record, or false to only update a live record. Returns 404 if the record's mode does not match. Omit to update the record regardless of mode" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_v1" } } } } } }, "put": { "summary": "Update a record", "operationId": "put_api_v1_records_by_id", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the record to update" }, { "name": "resolve_artifacts", "in": "query", "schema": { "type": "string" }, "description": "Set to \"false\" to return Artifacts (large text) fields as an artifact-ID reference instead of the full contents" }, { "name": "include_children", "in": "query", "schema": { "type": "string" }, "description": "Set to \"false\" to omit child records from the response. Defaults to including full child field data" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "field_values": { "type": "array", "items": { "type": "object" }, "description": "An array of { field_id, value } objects. Only works if the record type is editable" }, "add_child_records": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to add as child records" }, "remove_child_records": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to remove as child records" }, "parent_record_id": { "type": "integer", "description": "Record ID to link as the parent. Send null to remove the parent, omit to leave unchanged" }, "add_case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Case IDs to link to the record (at most 5)" }, "remove_case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Case IDs to unlink from the record (at most 5)" }, "test_mode": { "type": "boolean", "description": "Set to true to only update a test record, or false to only update a live record. Returns 404 if the record's mode does not match. Omit to update the record regardless of mode" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record_v1" } } } } } } }, "/api/v1/records/{record_id}/artifacts/{id}": { "get": { "summary": "Get a record artifact", "operationId": "get_api_v1_records_by_record_id_artifacts_by_id", "description": "Retrieve the full contents of an Artifact (large text) field by its ID.", "tags": [ "Records" ], "parameters": [ { "name": "record_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the record" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the record artifact" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The record artifact ID" }, "value": { "type": "string", "description": "The record artifact's value" }, "record_field": { "type": "object", "description": "The record field, with its id and name" }, "created_at": { "type": "string", "description": "When the record artifact was created" }, "updated_at": { "type": "string", "description": "When the record artifact was last updated" } } } } } } } } }, "/api/v1/records/query": { "post": { "summary": "Query records", "operationId": "post_api_v1_records_query", "description": "Run an aggregation query over records of a record type — counts, sums, averages, and grouped breakdowns — without retrieving individual records.", "tags": [ "Records" ], "parameters": [ { "name": "test_mode", "in": "query", "schema": { "type": "string" }, "description": "Set to \"true\" to run the query against test records only (defaults to false)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_type_id": { "type": "integer", "description": "The numeric ID of the record type to query" }, "aggregations": { "type": "array", "items": { "type": "object" }, "description": "Aggregation functions to compute (COUNT, SUM, AVG, MIN, MAX, MEDIAN), at most 5" }, "filters": { "type": "array", "items": { "type": "object" }, "description": "Filter conditions to narrow records before aggregation, ANDed together (at most 50)" }, "group_by": { "type": "array", "items": { "type": "object" }, "description": "Field references to group results by (at most 2)" }, "time_range": { "type": "object", "description": "Restrict which records are included, by rolling preset or custom range. Set `field` to `created_at` (default) or `updated_at` to choose the timestamp column filtered. When a `rolling_date_range` preset is set, any `range_start`/`range_end` are ignored; otherwise `range_start` must be before `range_end`." }, "timezone": { "type": "string", "description": "IANA timezone name applied to the query's time handling (defaults to UTC)" }, "parent_ids": { "type": "array", "items": { "type": "integer" }, "description": "Parent record IDs (max 100). Restricts the query to first-degree children" }, "order_by": { "type": "object", "description": "Sort the output rows by a column and direction" }, "limit": { "type": "integer", "description": "Cap on the number of rows returned, between 1 and 1000" } }, "required": [ "record_type_id", "aggregations" ] } } } }, "responses": { "200": { "description": "A JSON object with rows (an array of flat result objects) and meta (row_count, truncated, and columns)." }, "400": { "description": "The request body is not valid JSON, or a required query, filter, grouping, parent ID, or limit value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsQueryError" } } } }, "504": { "description": "The query took too long to run. Narrow its time range, reduce the number of aggregations or groupings, or retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordsQueryError" } } } } } } }, "/api/v1/reporting/flow_usage": { "get": { "summary": "Get flow usage by team", "operationId": "get_api_v1_reporting_flow_usage", "description": "Retrieve the tenant's flow usage against its licensed flow limit, broken down by team. Each team shows how many flows its stories use and how many flows are allocated to it. Teams without an allocation share the tenant's unallocated flows.\n\nFlow counts are recalculated whenever a story changes rather than on each request.\n\nOnly tenant owners can call this endpoint, and it is only available to tenants on the flows pricing model.", "tags": [ "Reporting" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": "20" }, "description": "Number of teams per page (max 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/team_flow_usage" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "flows": { "type": "object", "properties": { "used": { "type": "integer", "description": "Flows currently used across the tenant" }, "limit": { "type": "integer", "description": "Licensed flow limit for the tenant" }, "allocated": { "type": "integer", "description": "Flows allocated to specific teams" }, "unallocated": { "type": "integer", "description": "Flows not allocated to any team, shared by teams without an allocation" } }, "description": "Tenant-wide flow usage" } } } } } }, "400": { "description": "Flow usage is not available because the tenant does not use the flows pricing model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reporting/time_saved": { "get": { "summary": "List time saved metrics", "operationId": "get_api_v1_reporting_time_saved", "tags": [ "Reporting" ], "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "ISO8601 date-time lower bound" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "ISO8601 date-time upper bound" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by team" }, { "name": "story_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by story" }, { "name": "action_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by action" }, { "name": "date_unit", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day", "week", "month" ], "default": "day" }, "description": "Bucket the results by this unit" }, { "name": "fill_gaps", "in": "query", "schema": { "type": "boolean", "default": "true" }, "description": "Fill buckets that have no data with zero values" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": "20" }, "description": "Number of results per page (max 500)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "time_saved": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The bucket date" }, "value": { "type": "number", "description": "Time saved in seconds for the bucket" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "One of team_id, story_id, or action_id does not resolve to a resource the API key can see. The message names which one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/run_script_environments": { "get": { "summary": "List run script environments", "operationId": "get_api_v1_run_script_environments", "description": "Returns the custom run script environments (runtimes) visible to the requesting user. Tenant owners see all environments; other users see environments in teams they belong to, plus environments with no team restrictions.", "tags": [ "Run Script Environments" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "data": { "$ref": "#/components/schemas/run_script_environment_list_data" }, "count": { "type": "integer", "description": "The number of environments returned" } } } } } }, "401": { "$ref": "#/components/responses/RunScriptEnvironmentUnauthorized" } } }, "post": { "summary": "Create a run script environment", "operationId": "post_api_v1_run_script_environments", "description": "Creates a custom run script environment. Send the file either as a multipart environment_file upload, or provide blob_signed_id from a prior direct upload. If a matching environment already exists it is reused. Returns 201 when a new environment is created, or 200 when an existing matching environment is reused. Requires STORY_MANAGE permission on the primary team.", "tags": [ "Run Script Environments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "primary_team_id": { "type": "integer", "description": "ID of the primary team that owns the environment" }, "environment_type": { "type": "string", "description": "The type of environment to create (e.g. lambda, cloud_tcr)" }, "name": { "type": "string", "description": "Environment name" }, "description": { "type": "string", "description": "Environment description" }, "environment_file": { "type": "string", "description": "The environment ZIP file, sent as a multipart upload. Provide this or blob_signed_id." }, "blob_signed_id": { "type": "string", "description": "Signed blob ID from a prior direct upload. Provide this or environment_file." }, "runtime": { "type": "string", "description": "Runtime identifier (required for lambda environments, e.g. python3.11)" }, "team_ids": { "type": "array", "items": { "type": "integer" }, "description": "Additional team IDs to share the environment with" } }, "required": [ "primary_team_id", "environment_type" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "data": { "$ref": "#/components/schemas/run_script_environment" }, "message": { "type": "string", "description": "A human-readable status message" } } } } } }, "400": { "description": "The request is missing a file, sends a file that is not a valid ZIP, exceeds the maximum file size, or omits a runtime for a lambda environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentError" } } } }, "401": { "$ref": "#/components/responses/RunScriptEnvironmentUnauthorized" }, "403": { "description": "The requester lacks STORY_MANAGE permission on the primary team, or environment creation is disabled for this environment type on the tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentForbiddenError" } } } } } } }, "/api/v1/run_script_environments/{id}": { "delete": { "summary": "Delete a run script environment", "operationId": "delete_api_v1_run_script_environments_by_id", "description": "Deletes a run script environment. Fails if the environment is in use by actions in live stories. Requires STORY_MANAGE permission on the primary team unless the requester is a tenant owner.", "tags": [ "Run Script Environments" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the environment" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "message": { "type": "string", "description": "A human-readable status message" } } } } } }, "400": { "description": "The environment is in use by actions in live stories, so it cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentError" } } } }, "401": { "$ref": "#/components/responses/RunScriptEnvironmentUnauthorized" }, "403": { "description": "The requester cannot see the environment, the environment has no primary team, or the requester lacks STORY_MANAGE permission on that team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentForbiddenError" } } } } } }, "get": { "summary": "Get a run script environment", "operationId": "get_api_v1_run_script_environments_by_id", "description": "Returns a single run script environment by ID.", "tags": [ "Run Script Environments" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the environment" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "data": { "$ref": "#/components/schemas/run_script_environment" } } } } } }, "401": { "$ref": "#/components/responses/RunScriptEnvironmentUnauthorized" } } } }, "/api/v1/run_script_environments/{id}/download": { "get": { "summary": "Download a run script environment file", "operationId": "get_api_v1_run_script_environments_by_id_download", "description": "Streams the environment's attached file with the appropriate Content-Type header.", "tags": [ "Run Script Environments" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the environment" } ], "responses": { "200": { "description": "Binary file content with the appropriate Content-Type header" }, "401": { "$ref": "#/components/responses/RunScriptEnvironmentUnauthorized" }, "404": { "description": "No environment with that ID exists, or it has no attached file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentError" } } } } } } }, "/api/v1/run_script_environments/direct_upload_url": { "post": { "summary": "Generate a direct upload URL", "operationId": "post_api_v1_run_script_environments_direct_upload_url", "description": "Returns a pre-signed URL for uploading an environment file directly to storage. Upload the file to the returned URL, then pass the returned blob_signed_id when creating the environment.", "tags": [ "Run Script Environments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the file to upload" }, "content_type": { "type": "string", "description": "The MIME type of the file (application/zip or application/x-zip-compressed)" }, "byte_size": { "type": "integer", "description": "The size of the file in bytes" }, "environment_type": { "type": "string", "description": "The type of environment the file is for" }, "checksum": { "type": "string", "description": "MD5 checksum of the file (e.g. output of md5 -q )" } }, "required": [ "filename", "content_type", "byte_size", "environment_type", "checksum" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request succeeded" }, "data": { "$ref": "#/components/schemas/direct_upload_url_result" } } } } } }, "400": { "description": "The content type is not a ZIP type, or the byte size exceeds the maximum file size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentError" } } } }, "401": { "$ref": "#/components/responses/RunScriptEnvironmentUnauthorized" }, "403": { "description": "Direct upload is not supported for this environment type, or environment creation is disabled for it on the tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentForbiddenError" } } } } } } }, "/api/v1/skills": { "get": { "summary": "List skills", "operationId": "get_api_v1_skills", "tags": [ "Skills" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Only return skills owned by this team" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter skills whose name contains this text" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "$ref": "#/components/schemas/skill" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a skill", "operationId": "post_api_v1_skills", "tags": [ "Skills" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team to create the skill for" }, "name": { "type": "string", "description": "Skill name. Lowercase alphanumeric with hyphens, unique within the team" }, "description": { "type": "string", "description": "What the skill does and when to use it. AI agents are shown only the name and description, and match a task against them to decide whether to load the skill" }, "body": { "type": "string", "description": "The full skill instructions, in markdown. Loaded only after the description matches the task at hand" }, "license": { "type": "string", "description": "License the skill is distributed under" }, "compatibility": { "type": "string", "description": "Free-text note on what the skill is compatible with" }, "metadata": { "type": "object", "description": "Flat map of string keys to string values. Sets the whole map, so send every key you want to keep" } }, "required": [ "team_id", "name", "description", "body" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/skill" } } } } } } }, "/api/v1/skills/{skill_name}": { "delete": { "summary": "Delete a skill", "operationId": "delete_api_v1_skills_by_skill_name", "tags": [ "Skills" ], "parameters": [ { "name": "skill_name", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The skill name" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "The team that owns the skill" } ], "responses": { "204": { "description": "Empty response on success" }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Get a skill", "operationId": "get_api_v1_skills_by_skill_name", "tags": [ "Skills" ], "parameters": [ { "name": "skill_name", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The skill name" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "The team that owns the skill" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/skill" } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a skill", "operationId": "patch_api_v1_skills_by_skill_name", "description": "Renaming a skill also rewrites the skill's name in every AI action that references it.", "tags": [ "Skills" ], "parameters": [ { "name": "skill_name", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The skill name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team that owns the skill" }, "name": { "type": "string", "description": "Renames the skill" }, "description": { "type": "string", "description": "What the skill does and when to use it. AI agents are shown only the name and description, and match a task against them to decide whether to load the skill" }, "body": { "type": "string", "description": "The full skill instructions, in markdown. Loaded only after the description matches the task at hand" }, "license": { "type": "string", "description": "License the skill is distributed under" }, "compatibility": { "type": "string", "description": "Free-text note on what the skill is compatible with" }, "metadata": { "type": "object", "description": "Flat map of string keys to string values. Sets the whole map, so send every key you want to keep" } }, "required": [ "team_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/skill" } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a skill", "operationId": "put_api_v1_skills_by_skill_name", "description": "Renaming a skill also rewrites the skill's name in every AI action that references it.", "tags": [ "Skills" ], "parameters": [ { "name": "skill_name", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The skill name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team that owns the skill" }, "name": { "type": "string", "description": "Renames the skill" }, "description": { "type": "string", "description": "What the skill does and when to use it. AI agents are shown only the name and description, and match a task against them to decide whether to load the skill" }, "body": { "type": "string", "description": "The full skill instructions, in markdown. Loaded only after the description matches the task at hand" }, "license": { "type": "string", "description": "License the skill is distributed under" }, "compatibility": { "type": "string", "description": "Free-text note on what the skill is compatible with" }, "metadata": { "type": "object", "description": "Flat map of string keys to string values. Sets the whole map, so send every key you want to keep" } }, "required": [ "team_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/skill" } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories": { "get": { "summary": "List stories", "operationId": "get_api_v1_stories", "description": "Retrieve a list of stories.", "tags": [ "Stories" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Return stories belonging to this team" }, { "name": "folder_id", "in": "query", "schema": { "type": "integer" }, "description": "Return stories in this folder" }, { "name": "tags[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "An array of tag names to filter by" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "A string that searches against story name" }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "SEND_TO_STORY_ENABLED", "HIGH_PRIORITY", "API_ENABLED", "PUBLISHED", "FAVORITE", "CHANGE_CONTROL_ENABLED", "CHANGE_CONTROL_DISABLED", "ENABLED", "DISABLED", "LOCKED" ] }, "description": "Filter the results" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "NAME", "NAME_DESC", "RECENTLY_EDITED", "LEAST_RECENTLY_EDITED", "ACTION_COUNT_ASC", "ACTION_COUNT_DESC", "CONCURRENT_RUNS_COUNT_DESC", "PENDING_ACTION_RUNS_COUNT_DESC", "NOT_WORKING_ACTIONS_COUNT_DESC" ] }, "description": "Order the results" }, { "name": "include_live_activity", "in": "query", "schema": { "type": "boolean", "default": "false" }, "description": "When set to true, includes live activity metrics like pending_action_runs_count, concurrent_runs_count, tokens_used_percentage, and not_working_actions_count" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "stories": { "type": "array", "items": { "$ref": "#/components/schemas/story" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a story", "operationId": "post_api_v1_stories", "description": "Create a story in Tines.", "tags": [ "Stories" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "ID of team to which the story should be added" }, "name": { "type": "string", "description": "The story name" }, "description": { "type": "string", "description": "A user-defined description of the story" }, "keep_events_for": { "type": "integer", "description": "Event retention period in seconds. One of 3600, 21600, 86400, 259200, 604800, 1209600, 2592000, 5184000, 7776000, 15552000, or 31536000" }, "folder_id": { "type": "integer", "description": "ID of folder to which the story should be added" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "An array of strings used to create tags to classify the story" }, "disabled": { "type": "boolean", "default": "false", "description": "Whether the story is disabled" }, "priority": { "type": "boolean", "default": "false", "description": "Whether this is a high priority story" } }, "required": [ "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } }, "400": { "description": "team_id is missing, or tags is not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}": { "delete": { "summary": "Delete a story", "operationId": "delete_api_v1_stories_by_id", "description": "Delete a story.", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a story", "operationId": "get_api_v1_stories_by_id", "description": "Retrieve a single story.", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story to retrieve" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "description": "The mode of the story to retrieve" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "The ID of the draft to retrieve" }, { "name": "include_live_activity", "in": "query", "schema": { "type": "boolean", "default": "false" }, "description": "When set to true, includes live activity metrics like pending_action_runs_count, concurrent_runs_count, and tokens_used_percentage" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } } } }, "patch": { "summary": "Update a story", "operationId": "patch_api_v1_stories_by_id", "description": "Update a story. Defaults to a draft called \"test\" if change control is enabled on the story and no draft_id is provided.", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The story name" }, "description": { "type": "string", "description": "A user-defined description of the story" }, "add_tag_names": { "type": "array", "items": { "type": "string" }, "description": "An array of tag names to add to the story" }, "remove_tag_names": { "type": "array", "items": { "type": "string" }, "description": "An array of tag names to remove from the story" }, "keep_events_for": { "type": "integer", "description": "Event retention period in seconds. One of 3600, 21600, 86400, 259200, 604800, 1209600, 2592000, 5184000, 7776000, 15552000, or 31536000" }, "disabled": { "type": "boolean", "description": "Whether the story is disabled from running" }, "locked": { "type": "boolean", "description": "Whether the story is locked, preventing edits" }, "priority": { "type": "boolean", "description": "Whether the story runs with high priority" }, "webhook_api_enabled": { "type": "boolean", "description": "Whether webhook API is enabled. If enabling, api_entry_action_id and api_exit_action_ids must also be specified" }, "api_entry_action_id": { "type": "integer", "description": "The ID of the entry action for this API enabled story (action must be of type webhook)" }, "api_exit_action_ids": { "type": "array", "items": { "type": "integer" }, "description": "An array of IDs describing exit actions for this API enabled story" }, "send_to_story_access_source": { "type": "string", "enum": [ "STS", "STS_AND_WORKBENCH", "WORKBENCH", "OFF" ], "description": "Indicates if send to story is enabled and where it can be used. If enabling, entry_action_id and exit_action_ids must also be specified" }, "entry_action_id": { "type": "integer", "description": "The ID of the entry action for this send to story enabled story (action must be of type webhook)" }, "exit_action_ids": { "type": "array", "items": { "type": "integer" }, "description": "An array of IDs describing exit actions for this send to story enabled story" }, "send_to_story_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "default": "TEAM", "description": "Controls who is allowed to send to this story. If using SPECIFIC_TEAMS must also specify shared_team_slugs" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "List of teams' slugs that can send to this story. Required to set send_to_story_access to SPECIFIC_TEAMS" }, "send_to_story_skill_use_requires_confirmation": { "type": "boolean", "description": "Whether Workbench should ask for confirmation before running this story" }, "team_id": { "type": "integer", "description": "The ID of the team to move the story to" }, "folder_id": { "type": "integer", "description": "The ID of the folder to move the story to, or an empty value for the root folder" }, "change_control_enabled": { "type": "boolean", "description": "Whether change control is enabled" }, "draft_id": { "type": "integer", "description": "The ID of the draft to update" }, "monitor_failures": { "type": "boolean", "description": "Whether monitor failures is enabled on the story" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } }, "400": { "description": "add_tag_names is not an array, or a supplied owner or recipient is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a story", "operationId": "put_api_v1_stories_by_id", "description": "Update a story. Defaults to a draft called \"test\" if change control is enabled on the story and no draft_id is provided.", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The story name" }, "description": { "type": "string", "description": "A user-defined description of the story" }, "add_tag_names": { "type": "array", "items": { "type": "string" }, "description": "An array of tag names to add to the story" }, "remove_tag_names": { "type": "array", "items": { "type": "string" }, "description": "An array of tag names to remove from the story" }, "keep_events_for": { "type": "integer", "description": "Event retention period in seconds. One of 3600, 21600, 86400, 259200, 604800, 1209600, 2592000, 5184000, 7776000, 15552000, or 31536000" }, "disabled": { "type": "boolean", "description": "Whether the story is disabled from running" }, "locked": { "type": "boolean", "description": "Whether the story is locked, preventing edits" }, "priority": { "type": "boolean", "description": "Whether the story runs with high priority" }, "webhook_api_enabled": { "type": "boolean", "description": "Whether webhook API is enabled. If enabling, api_entry_action_id and api_exit_action_ids must also be specified" }, "api_entry_action_id": { "type": "integer", "description": "The ID of the entry action for this API enabled story (action must be of type webhook)" }, "api_exit_action_ids": { "type": "array", "items": { "type": "integer" }, "description": "An array of IDs describing exit actions for this API enabled story" }, "send_to_story_access_source": { "type": "string", "enum": [ "STS", "STS_AND_WORKBENCH", "WORKBENCH", "OFF" ], "description": "Indicates if send to story is enabled and where it can be used. If enabling, entry_action_id and exit_action_ids must also be specified" }, "entry_action_id": { "type": "integer", "description": "The ID of the entry action for this send to story enabled story (action must be of type webhook)" }, "exit_action_ids": { "type": "array", "items": { "type": "integer" }, "description": "An array of IDs describing exit actions for this send to story enabled story" }, "send_to_story_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "default": "TEAM", "description": "Controls who is allowed to send to this story. If using SPECIFIC_TEAMS must also specify shared_team_slugs" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "List of teams' slugs that can send to this story. Required to set send_to_story_access to SPECIFIC_TEAMS" }, "send_to_story_skill_use_requires_confirmation": { "type": "boolean", "description": "Whether Workbench should ask for confirmation before running this story" }, "team_id": { "type": "integer", "description": "The ID of the team to move the story to" }, "folder_id": { "type": "integer", "description": "The ID of the folder to move the story to, or an empty value for the root folder" }, "change_control_enabled": { "type": "boolean", "description": "Whether change control is enabled" }, "draft_id": { "type": "integer", "description": "The ID of the draft to update" }, "monitor_failures": { "type": "boolean", "description": "Whether monitor failures is enabled on the story" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } }, "400": { "description": "add_tag_names is not an array, or a supplied owner or recipient is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}/change_request": { "post": { "summary": "Create a change request", "operationId": "post_api_v1_stories_by_id_change_request", "description": "Create a change request.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The change request name" }, "description": { "type": "string", "description": "A user-defined description of the change request. For mentioning users, use the notation <@user-2435>, replacing '2435' with the user ID" }, "draft_id": { "type": "integer", "description": "The ID of the draft" } } } } } }, "responses": { "200": { "description": "The created change request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The live story ID" }, "draft_id": { "type": "integer", "description": "ID of the selected draft" }, "draft_name": { "type": "string", "description": "Name of the selected draft" }, "change_request": { "type": "object", "description": "The change request, containing id, name, description, status (PENDING or APPROVED), participants, and the live_story_export and draft_export" } } } } } } } } }, "/api/v1/stories/{id}/change_request/ai_description": { "get": { "summary": "Generate a change request description", "operationId": "get_api_v1_stories_by_id_change_request_ai_description", "description": "Generate a new description for the changes captured in the change request. AI features must be enabled for a successful response.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "ID of the draft" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "change_request_ai_description": { "type": "string", "description": "The generated description of the changes captured in the change request" } } } } } } } } }, "/api/v1/stories/{id}/change_request/approve": { "post": { "summary": "Approve a change request", "operationId": "post_api_v1_stories_by_id_change_request_approve", "description": "Approve a change request.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_request_id": { "type": "integer", "description": "The ID of the change request" } }, "required": [ "change_request_id" ] } } } }, "responses": { "200": { "description": "The status of the change request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The live story ID" }, "draft_id": { "type": "integer", "description": "ID of the draft containing the change request" }, "draft_name": { "type": "string", "description": "Name of the draft containing the change request" }, "change_request": { "type": "object", "description": "The change request, containing id, status (PENDING or APPROVED), and participants" } } } } } }, "401": { "description": "The API key lacks CHANGE_CONTROL_MANAGE, CHANGE_CONTROL_REVIEW, or STORY_MANAGE on the team; or it authenticates as the change request's own author on a tenant that requires approvals; or the story requires owner approval and the key is not a story owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}/change_request/cancel": { "post": { "summary": "Cancel or reject a change request", "operationId": "post_api_v1_stories_by_id_change_request_cancel", "description": "Cancel a change request. If you're not the author of the change request, this rejects it instead of canceling it.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_request_id": { "type": "integer", "description": "The ID of the change request" } }, "required": [ "change_request_id" ] } } } }, "responses": { "200": { "description": "The change request, which will be null once canceled or rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The live story ID" }, "draft_id": { "type": "integer", "description": "ID of the draft containing the change request" }, "draft_name": { "type": "string", "description": "Name of the draft containing the change request" }, "change_request": { "type": "object", "nullable": true, "description": "The change request, which will be null" } } } } } } } } }, "/api/v1/stories/{id}/change_request/promote": { "post": { "summary": "Promote a change request", "operationId": "post_api_v1_stories_by_id_change_request_promote", "description": "Promote changes to the live story.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_request_id": { "type": "integer", "description": "The ID of the change request" }, "bypass_approval": { "type": "boolean", "default": "false", "description": "When true, a pending change request is promoted straight to the live story, skipping the approval step. Requires permission to promote on the story's team (STORY_MANAGE)" }, "bypass_approval_reason": { "type": "string", "description": "A human-readable reason recorded in the audit trail. When bypass_approval is true and no reason is supplied, the recorded message defaults to \"Approval bypassed via API\"" }, "delete_draft": { "type": "boolean", "default": "false", "description": "When true, the draft used for the change request is deleted after promotion, matching the web app behavior. Defaults to false, which leaves the draft on the story" } }, "required": [ "change_request_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } } } } }, "/api/v1/stories/{id}/change_request/reject": { "post": { "summary": "Cancel or reject a change request", "operationId": "post_api_v1_stories_by_id_change_request_reject", "description": "Cancel a change request. If you're not the author of the change request, this rejects it instead of canceling it.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "change_request_id": { "type": "integer", "description": "The ID of the change request" } }, "required": [ "change_request_id" ] } } } }, "responses": { "200": { "description": "The change request, which will be null once canceled or rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The live story ID" }, "draft_id": { "type": "integer", "description": "ID of the draft containing the change request" }, "draft_name": { "type": "string", "description": "Name of the draft containing the change request" }, "change_request": { "type": "object", "nullable": true, "description": "The change request, which will be null" } } } } } } } } }, "/api/v1/stories/{id}/change_request/view": { "get": { "summary": "View a change request", "operationId": "get_api_v1_stories_by_id_change_request_view", "description": "View the current change request for a story. If a test story has changes but a change request has not been submitted, change_request will be null.", "tags": [ "Stories > Change control" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "The ID of the draft" } ], "responses": { "200": { "description": "The current change request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The live story ID" }, "draft_id": { "type": "integer", "description": "ID of the selected draft" }, "draft_name": { "type": "string", "description": "Name of the selected draft" }, "change_request": { "type": "object", "nullable": true, "description": "The change request, containing id, name, description, status (PENDING or APPROVED), participants, and the live_story_export and draft_export. Null if no change request has been submitted" } } } } } } } } }, "/api/v1/stories/{id}/disable": { "post": { "summary": "Disable a story", "operationId": "post_api_v1_stories_by_id_disable", "description": "Update the disabled state of a story. This can be used to disable a story that has change control enabled, bypassing the change control approval process.", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "The new disabled state of the story" } }, "required": [ "disabled" ] } } } }, "responses": { "200": { "description": "The new disabled state of the story", "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "The disabled state of the story" } } } } } } } } }, "/api/v1/stories/{id}/drafts": { "get": { "summary": "List drafts", "operationId": "get_api_v1_stories_by_id_drafts", "description": "Retrieve a list of drafts for a story.", "tags": [ "Stories > Drafts" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "$ref": "#/components/schemas/story" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a draft", "operationId": "post_api_v1_stories_by_id_drafts", "description": "Create a new draft for a story.", "tags": [ "Stories > Drafts" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the draft" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } }, "400": { "description": "name is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}/drafts/{draft_id}": { "delete": { "summary": "Delete a draft", "operationId": "delete_api_v1_stories_by_id_drafts_by_draft_id", "description": "Delete a draft for a story.", "tags": [ "Stories > Drafts" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story" }, { "name": "draft_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the draft" } ], "responses": { "204": { "description": "Empty response on success" }, "404": { "description": "The story is not visible to the API key, or the draft does not belong to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}/export": { "get": { "summary": "Export a story", "operationId": "get_api_v1_stories_by_id_export", "description": "Export a story to a transferable story file.", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story to export" }, { "name": "randomize_urls", "in": "query", "schema": { "type": "boolean" }, "description": "Whether the story's page and webhook URLs should be randomized" }, { "name": "clear_recipients", "in": "query", "schema": { "type": "boolean" }, "description": "Whether the story's monitoring and email recipient fields should be cleared" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "ID of the draft to export" } ], "responses": { "200": { "description": "A JSON object representing the story in exported form." } } } }, "/api/v1/stories/{id}/owners": { "delete": { "summary": "Remove a story owner", "operationId": "delete_api_v1_stories_by_id_owners", "description": "Delete a story owner for a story.", "tags": [ "Stories > Owners" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story in which the story owner should be deleted" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The ID of the user to remove as a story owner. The user must be an existing story owner" } }, "required": [ "user_id" ] } } } }, "responses": { "204": { "description": "Empty response on success" } } }, "post": { "summary": "Add a story owner", "operationId": "post_api_v1_stories_by_id_owners", "description": "Create a story owner for a story.", "tags": [ "Stories > Owners" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story in which the story owner should be created" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The ID of the user to add as a story owner. The user must be a member of the team in which the story exists" } }, "required": [ "user_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } } } } }, "/api/v1/stories/{id}/pending_actions": { "get": { "summary": "List pending actions", "operationId": "get_api_v1_stories_by_id_pending_actions", "description": "Retrieve a list of actions in a story that currently have pending action runs, ordered by the number of pending runs (highest first).", "tags": [ "Stories" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search against action names" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "description": "The mode of the story (defaults to LIVE)" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "Return actions for a specific draft" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending_actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Action ID" }, "name": { "type": "string", "description": "Name of the action" }, "type": { "type": "string", "description": "Action type" }, "pending_action_runs_count": { "type": "integer", "description": "Number of pending action runs for this action" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/stories/{id}/recipients": { "delete": { "summary": "Remove a story recipient", "operationId": "delete_api_v1_stories_by_id_recipients", "description": "Delete a story recipient for a story. The recipient will no longer receive story monitoring communications and will be removed from the recipients list.", "tags": [ "Stories > Recipients" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story in which the story recipient should be deleted" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The email or webhook URL that should no longer receive story monitoring communications" }, "draft_id": { "type": "integer", "description": "The ID of the draft to update" } }, "required": [ "address" ] } } } }, "responses": { "204": { "description": "Empty response on success" } } }, "post": { "summary": "Add a story recipient", "operationId": "post_api_v1_stories_by_id_recipients", "description": "Create a story recipient for a story. The recipients will receive story monitoring communications when enabled.", "tags": [ "Stories > Recipients" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the story in which the story recipient should be created" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The email or webhook URL that should receive story monitoring communications" }, "draft_id": { "type": "integer", "description": "The ID of the draft to update" } }, "required": [ "address" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } }, "400": { "description": "address is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/stories/{id}/runs": { "get": { "summary": "List story runs", "operationId": "get_api_v1_stories_by_id_runs", "description": "Retrieve a list of story runs.", "tags": [ "Stories > Story runs" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "description": "The mode of the story" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "Return runs for a specific draft" }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve story runs that started after this time (ISO 8601 timestamp)" }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "Only retrieve story runs that started until this time (ISO 8601 timestamp)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "story_runs": { "type": "array", "items": { "$ref": "#/components/schemas/story_run" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/stories/{id}/runs/{story_run_guid}": { "get": { "summary": "List story run events", "operationId": "get_api_v1_stories_by_id_runs_by_story_run_guid", "description": "Retrieve a list of events for a story run.", "tags": [ "Stories > Story runs" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "story_run_guid", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The guid of the story run" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "description": "The mode of the story" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "Return events for a specific draft" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "story_run_events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID of the event" }, "action_id": { "type": "integer", "description": "ID of the action that emitted the event" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of the date and time the event was emitted" }, "is_reemitted": { "type": "boolean", "description": "Whether this event has been re-emitted" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/stories/{id}/runs/{story_run_guid}/summary": { "get": { "summary": "Get story run summary", "operationId": "get_api_v1_stories_by_id_runs_by_story_run_guid_summary", "description": "Retrieve metadata for a specific story run.", "tags": [ "Stories > Story runs" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "story_run_guid", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The guid of the story run" }, { "name": "story_mode", "in": "query", "schema": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "description": "The mode of the story" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "Return the run for a specific draft" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "story_run": { "$ref": "#/components/schemas/story_run" } } } } } } } } }, "/api/v1/stories/{id}/versions": { "get": { "summary": "List story versions", "operationId": "get_api_v1_stories_by_id_versions", "description": "Retrieve a list of story versions.", "tags": [ "Stories > Versions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "draft_id", "in": "query", "schema": { "type": "integer" }, "description": "The ID of the draft" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "story_versions": { "type": "array", "items": { "$ref": "#/components/schemas/story_version" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a story version", "operationId": "post_api_v1_stories_by_id_versions", "description": "Create a story version.", "tags": [ "Stories > Versions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The story version name" }, "draft_id": { "type": "integer", "description": "Specify the draft for which to create a version" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_version" } } } } } } }, "/api/v1/stories/{id}/versions/{version_id}": { "delete": { "summary": "Delete a story version", "operationId": "delete_api_v1_stories_by_id_versions_by_version_id", "description": "Delete a story version.", "tags": [ "Stories > Versions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "version_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story version to delete" } ], "responses": { "200": { "description": "The deleted story version ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "destroyed_id": { "type": "integer", "description": "Story version ID" } } } } } } } }, "get": { "summary": "Get a story version", "operationId": "get_api_v1_stories_by_id_versions_by_version_id", "description": "Retrieve a story version.", "tags": [ "Stories > Versions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "version_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story version to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_version" } } } } } }, "post": { "summary": "Update a story version", "operationId": "post_api_v1_stories_by_id_versions_by_version_id", "description": "Update a story version.", "tags": [ "Stories > Versions" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story" }, { "name": "version_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the story version to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the story version" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story_version" } } } } } } }, "/api/v1/stories/batch": { "delete": { "summary": "Batch delete stories", "operationId": "delete_api_v1_stories_batch", "description": "Delete many stories. Sync sources and live read-only sync destinations are skipped.", "tags": [ "Stories" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "description": "The IDs of the stories to delete" } }, "required": [ "ids" ] } } } }, "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/stories/import": { "post": { "summary": "Import a story", "operationId": "post_api_v1_stories_import", "description": "Import a new story. Note that if the story data includes embedded substories these will not be imported.", "tags": [ "Stories" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_name": { "type": "string", "description": "The new name for the story" }, "data": { "type": "object", "description": "JSON object representing the story in exported form" }, "team_id": { "type": "integer", "description": "ID of team to which the story should be added" }, "folder_id": { "type": "integer", "description": "ID of folder to which the story should be added" }, "mode": { "type": "string", "enum": [ "new", "versionReplace" ], "default": "new", "description": "Create a new story or update an existing one by name" }, "draft_name": { "type": "string", "description": "Custom name for the draft when change control is enabled. Defaults to \"Imported story\" if not provided" } }, "required": [ "new_name", "data", "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/story" } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tags": { "get": { "summary": "List tags", "operationId": "get_api_v1_tags", "tags": [ "Tags" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter tags by team" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "$ref": "#/components/schemas/tag" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a tag", "operationId": "post_api_v1_tags", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team to create the tag for" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color: one of purple, blue, gold, green, magenta, red, orange, mint, or a #RRGGBB hex value" } }, "required": [ "team_id", "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag" } } } }, "422": { "$ref": "#/components/responses/InvalidTagColor" } } } }, "/api/v1/tags/{id}": { "delete": { "summary": "Delete a tag", "operationId": "delete_api_v1_tags_by_id", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The tag ID" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Remove the tag from a single team; omit to delete the tag entirely" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a tag", "operationId": "get_api_v1_tags_by_id", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The tag ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag" } } } } } }, "patch": { "summary": "Update a tag", "operationId": "patch_api_v1_tags_by_id", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The tag ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated tag name" }, "color": { "type": "string", "description": "Tag color: one of purple, blue, gold, green, magenta, red, orange, mint, or a #RRGGBB hex value" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag" } } } }, "422": { "$ref": "#/components/responses/InvalidTagColor" } } }, "put": { "summary": "Update a tag", "operationId": "put_api_v1_tags_by_id", "tags": [ "Tags" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The tag ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated tag name" }, "color": { "type": "string", "description": "Tag color: one of purple, blue, gold, green, magenta, red, orange, mint, or a #RRGGBB hex value" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag" } } } }, "422": { "$ref": "#/components/responses/InvalidTagColor" } } } }, "/api/v1/teams": { "get": { "summary": "List teams", "operationId": "get_api_v1_teams", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "all", "standard", "personal_only" ] }, "description": "Filter teams by scope (defaults to standard)" }, { "name": "include_personal_teams", "in": "query", "schema": { "type": "boolean" }, "description": "Deprecated: use scope instead. Include personal teams in the response (defaults to false)" }, { "name": "include_drafts", "in": "query", "schema": { "type": "boolean" }, "description": "Deprecated: use scope instead. Include draft (personal) teams in the response (defaults to false)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/team" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a team", "operationId": "post_api_v1_teams", "tags": [ "Teams (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The team name" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/team" } } } } } } }, "/api/v1/teams/{id}": { "delete": { "summary": "Delete a team", "operationId": "delete_api_v1_teams_by_id", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the team to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a team", "operationId": "get_api_v1_teams_by_id", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the team to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/team" } } } } } }, "patch": { "summary": "Update a team", "operationId": "patch_api_v1_teams_by_id", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the team to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the team" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/team" } } } } } }, "put": { "summary": "Update a team", "operationId": "put_api_v1_teams_by_id", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the team to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the team" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/team" } } } } } } }, "/api/v1/teams/{id}/destroy_static_external_id": { "post": { "summary": "Destroy a team's static external ID", "operationId": "post_api_v1_teams_by_id_destroy_static_external_id", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the team" } ], "responses": { "200": { "description": "The ID of the destroyed team static external ID" } } } }, "/api/v1/teams/{id}/invite_member": { "post": { "summary": "Invite a team member", "operationId": "post_api_v1_teams_by_id_invite_member", "description": "Invite a user to join a team. Provide either user_id or email, but not both.", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the team" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the user. Provide either email or user_id, not both" }, "user_id": { "type": "integer", "description": "ID of an existing user in the tenant. Provide either user_id or email, not both" }, "role": { "type": "string", "description": "Which role the user should have on the team. Supports both default and custom roles" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/team_member" } } } } } } }, "/api/v1/teams/{id}/members": { "get": { "summary": "List team members", "operationId": "get_api_v1_teams_by_id_members", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the team" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/team_member" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/teams/{id}/remove_member": { "post": { "summary": "Remove a team member", "operationId": "post_api_v1_teams_by_id_remove_member", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the team" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "ID of the user to remove" } }, "required": [ "user_id" ] } } } }, "responses": { "200": { "description": "The ID of the removed membership", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted_id": { "type": "integer", "description": "ID of the removed membership" } } } } } } } } }, "/api/v1/teams/{id}/resend_invitation": { "post": { "summary": "Resend a member invitation", "operationId": "post_api_v1_teams_by_id_resend_invitation", "tags": [ "Teams (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the team" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "ID of the user to reinvite" } }, "required": [ "user_id" ] } } } }, "responses": { "200": { "description": "The reinvited user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" }, "email": { "type": "string", "description": "User email" }, "is_admin": { "type": "boolean", "description": "Whether the user is an admin" }, "created_at": { "type": "string", "description": "When the user was created" }, "last_seen": { "type": "string", "nullable": true, "description": "When the user was last seen in the platform" }, "invitation_accepted": { "type": "boolean", "description": "Whether the user accepted the invitation to join the team" } } } } } } } } }, "/api/v1/user_credentials": { "get": { "summary": "List credentials", "operationId": "get_api_v1_user_credentials", "tags": [ "User credentials (v1)" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "List credentials for the given team" }, { "name": "folder_id", "in": "query", "schema": { "type": "integer" }, "description": "List credentials for the given folder" }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "UNUSED_IN_ACTIONS", "UNRESTRICTED", "RESTRICTED" ] }, "description": "Filter credentials" }, { "name": "include_references", "in": "query", "schema": { "type": "boolean" }, "description": "Set to true to include IDs of stories and actions referencing each credential (limited to 100 visible actions per credential)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (defaults to 20)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number (defaults to 1)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_credentials": { "type": "array", "items": { "$ref": "#/components/schemas/user_credential" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a credential", "operationId": "post_api_v1_user_credentials", "description": "Create a credential. Additional mode-specific parameters apply for JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, and MULTI_REQUEST credentials. For a test credential used in TEST mode of change control, provide live_credential_id.", "tags": [ "User credentials (v1)" ], "parameters": [ { "name": "include_references", "in": "query", "schema": { "type": "boolean" }, "description": "Set to true to include IDs of stories and actions referencing this credential (limited to 500 visible actions)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the credential" }, "mode": { "type": "string", "enum": [ "TEXT", "JWT", "OAUTH", "AWS", "MTLS", "HTTP_REQUEST_AGENT", "MULTI_REQUEST" ], "description": "The type of credential" }, "value": { "type": "string", "description": "Value of the credential (for TEXT credentials)" }, "team_id": { "type": "integer", "description": "ID of the team where the credential will be located" }, "folder_id": { "type": "integer", "description": "ID of the folder where the credential will be located" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this credential can be used (defaults to TEAM). SPECIFIC_TEAMS is a premium feature" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this credential can be used. Required to set read_access to SPECIFIC_TEAMS (defaults to [])" }, "description": { "type": "string", "description": "Description of the credential (defaults to \"\")" }, "metadata": { "type": "object", "description": "Key/value metadata relevant to the credential that can be referenced via the INFO path" }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "Domains where this credential can only be used in HTTP requests. Domain matching supports wildcards" }, "live_credential_id": { "type": "integer", "description": "ID of the live credential that this new test value corresponds to" }, "expires_at": { "type": "string", "description": "When the credential will expire (ISO 8601). Defaults to null" }, "expiry_notifications_enabled": { "type": "boolean", "description": "Whether expiry notifications are enabled (defaults to false)" }, "credential_notification_recipient_user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User IDs that will be sent credential notifications (e.g. expiry notifications)" } }, "required": [ "name", "mode", "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_credential" } } } } } } }, "/api/v1/user_credentials/{id}": { "delete": { "summary": "Delete a credential", "operationId": "delete_api_v1_user_credentials_by_id", "tags": [ "User credentials (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the credential to delete" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a credential", "operationId": "get_api_v1_user_credentials_by_id", "tags": [ "User credentials (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the credential to retrieve" }, { "name": "include_references", "in": "query", "schema": { "type": "boolean" }, "description": "Set to true to include IDs of stories and actions referencing this credential (limited to 500 visible actions)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_credential" } } } } } }, "patch": { "summary": "Update a credential", "operationId": "patch_api_v1_user_credentials_by_id", "description": "Update a credential. Additional mode-specific parameters apply for JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, and MULTI_REQUEST credentials. If the credential has a test value it can be modified using the is_test parameter.", "tags": [ "User credentials (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the credential to update" }, { "name": "include_references", "in": "query", "schema": { "type": "boolean" }, "description": "Set to true to include IDs of stories and actions referencing this credential (limited to 500 visible actions)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEXT", "JWT", "OAUTH", "AWS", "MTLS", "HTTP_REQUEST_AGENT", "MULTI_REQUEST" ], "description": "The type of credential" }, "value": { "type": "string", "description": "Value of the credential (for TEXT credentials)" }, "name": { "type": "string", "description": "Name of the credential" }, "folder_id": { "type": "integer", "description": "ID of the folder to move the credential to, or an empty value for the root folder" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this credential can be used (defaults to TEAM). SPECIFIC_TEAMS is a premium feature" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this credential can be used. Required to set read_access to SPECIFIC_TEAMS (defaults to [])" }, "description": { "type": "string", "description": "Description of the credential (defaults to \"\")" }, "metadata": { "type": "object", "description": "Key/value metadata for use in HTTP requests alongside the credential value" }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "Domains where this credential can only be used in HTTP requests. Domain matching supports wildcards" }, "test_credential_enabled": { "type": "boolean", "description": "Whether the credential is enabled for using a test credential" }, "is_test": { "type": "boolean", "description": "Whether the test credential should be updated. Requires test_credential_enabled true and an existing test credential" }, "expires_at": { "type": "string", "description": "When the credential will expire (ISO 8601). Defaults to null" }, "expiry_notifications_enabled": { "type": "boolean", "description": "Whether expiry notifications are enabled (defaults to false)" }, "credential_notification_recipient_user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User IDs that will be sent credential notifications (e.g. expiry notifications)" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_credential" } } } } } }, "put": { "summary": "Update a credential", "operationId": "put_api_v1_user_credentials_by_id", "description": "Update a credential. Additional mode-specific parameters apply for JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, and MULTI_REQUEST credentials. If the credential has a test value it can be modified using the is_test parameter.", "tags": [ "User credentials (v1)" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The ID of the credential to update" }, { "name": "include_references", "in": "query", "schema": { "type": "boolean" }, "description": "Set to true to include IDs of stories and actions referencing this credential (limited to 500 visible actions)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEXT", "JWT", "OAUTH", "AWS", "MTLS", "HTTP_REQUEST_AGENT", "MULTI_REQUEST" ], "description": "The type of credential" }, "value": { "type": "string", "description": "Value of the credential (for TEXT credentials)" }, "name": { "type": "string", "description": "Name of the credential" }, "folder_id": { "type": "integer", "description": "ID of the folder to move the credential to, or an empty value for the root folder" }, "read_access": { "type": "string", "enum": [ "TEAM", "GLOBAL", "SPECIFIC_TEAMS" ], "description": "Where this credential can be used (defaults to TEAM). SPECIFIC_TEAMS is a premium feature" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this credential can be used. Required to set read_access to SPECIFIC_TEAMS (defaults to [])" }, "description": { "type": "string", "description": "Description of the credential (defaults to \"\")" }, "metadata": { "type": "object", "description": "Key/value metadata for use in HTTP requests alongside the credential value" }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "Domains where this credential can only be used in HTTP requests. Domain matching supports wildcards" }, "test_credential_enabled": { "type": "boolean", "description": "Whether the credential is enabled for using a test credential" }, "is_test": { "type": "boolean", "description": "Whether the test credential should be updated. Requires test_credential_enabled true and an existing test credential" }, "expires_at": { "type": "string", "description": "When the credential will expire (ISO 8601). Defaults to null" }, "expiry_notifications_enabled": { "type": "boolean", "description": "Whether expiry notifications are enabled (defaults to false)" }, "credential_notification_recipient_user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User IDs that will be sent credential notifications (e.g. expiry notifications)" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_credential" } } } } } } }, "/api/v1/workbench": { "get": { "summary": "List Workbench conversations", "operationId": "get_api_v1_workbench", "description": "List AI conversations across all surfaces, including workbench, AI agents, and story authoring.", "tags": [ "Workbench (v1)" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search term to filter conversations by title" }, { "name": "favorited", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by favorited status" }, { "name": "creator_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter conversations by the ID of the creator (user)" }, { "name": "conversation_type", "in": "query", "schema": { "type": "string", "enum": [ "workbench", "task_agent", "chat_agent", "workbench_storyboard" ] }, "description": "Filter by conversation type. An invalid value returns a 400 response" }, { "name": "created_after", "in": "query", "schema": { "type": "string" }, "description": "Only return conversations created at or after this ISO 8601 timestamp" }, { "name": "created_before", "in": "query", "schema": { "type": "string" }, "description": "Only return conversations created at or before this ISO 8601 timestamp" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Set the number of results returned per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Specify the page of results to return if there are multiple pages. Defaults to page 1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "guid": { "type": "string", "description": "The conversation GUID" }, "title": { "type": "string", "description": "The conversation title" }, "source": { "type": "string", "description": "The source of the conversation, for example tines or slack" }, "conversation_type": { "type": "string", "description": "The type of conversation: workbench, task_agent, chat_agent, or workbench_storyboard" }, "source_type": { "type": "string", "nullable": true, "description": "The type of the resource the conversation is linked to, for example Story, or null if it has no source" }, "source_id": { "type": "integer", "nullable": true, "description": "The ID of the resource the conversation is linked to, or null if it has no source" }, "favorited": { "type": "boolean", "description": "Whether the conversation is favorited by the user" }, "creator_id": { "type": "integer", "description": "The ID of the user or agent that created the conversation" }, "creator_type": { "type": "string", "description": "The type of entity that created the conversation: User or Agent" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the conversation was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the conversation was last updated" }, "tool_uses_count": { "type": "integer", "description": "The total number of tool invocations performed during the conversation" }, "credits_used": { "type": "integer", "description": "The total number of Tines AI credits consumed by the conversation" }, "billed_cost": { "type": "object", "description": "The total cost of the conversation, as an object with currency (for example usd) and amount (a string formatted to two decimal places)" } } } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "A creation timestamp is invalid, created_after is not before created_before, or conversation_type is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workbench/{guid}": { "get": { "summary": "Get a Workbench conversation", "operationId": "get_api_v1_workbench_by_guid", "description": "Retrieve a Workbench conversation, including metadata, aggregate AI usage, and the full transcript.", "tags": [ "Workbench (v1)" ], "parameters": [ { "name": "guid", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The GUID of the conversation to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "guid": { "type": "string", "description": "The conversation GUID" }, "title": { "type": "string", "description": "The conversation title" }, "source": { "type": "string", "description": "The source of the conversation, for example tines or slack" }, "conversation_type": { "type": "string", "description": "The type of conversation: workbench, task_agent, chat_agent, or workbench_storyboard" }, "source_type": { "type": "string", "nullable": true, "description": "The type of the resource the conversation is linked to, for example Story, or null if it has no source" }, "source_id": { "type": "integer", "nullable": true, "description": "The ID of the resource the conversation is linked to, or null if it has no source" }, "favorited": { "type": "boolean", "description": "Whether the conversation is favorited by the user" }, "creator_id": { "type": "integer", "description": "The ID of the user or agent that created the conversation" }, "creator_type": { "type": "string", "description": "The type of entity that created the conversation: User or Agent" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the conversation was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the conversation was last updated" }, "tool_uses_count": { "type": "integer", "description": "The total number of tool invocations performed during the conversation" }, "credits_used": { "type": "integer", "description": "The total number of Tines AI credits consumed by the conversation" }, "billed_cost": { "type": "object", "description": "The total cost of the conversation, as an object with currency (for example usd) and amount (a string formatted to two decimal places)" }, "status": { "type": "string", "description": "The current status of the conversation: in_progress, complete, cancelled, or failed" }, "usage": { "type": "object", "description": "Aggregate model token usage. Contains input_tokens, output_tokens, cached_read_input_tokens, cached_write_input_tokens, and model_ids (array of strings)" }, "steps": { "type": "array", "items": { "type": "object" }, "description": "Conversation messages including user, assistant, agent, and tool interactions" } } } } } } } } }, "/api/v2/record_types": { "get": { "summary": "List record types", "operationId": "get_api_v2_record_types", "description": "List the record types visible to the calling token, each with its custom fields. Use this to discover record type ids and field ids before reading records. Results are keyset-paginated.", "tags": [ "Records" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Narrow to record types readable by this team. An unknown or unauthorized team returns 404." }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "NAME", "CREATED_AT", "UPDATED_AT" ] }, "description": "Attribute to sort by (case-insensitive). Defaults to NAME. Pair with `direction` to choose ascending or descending." }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "description": "Sort direction (case-insensitive). Defaults to ASC." }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Page size, 1-500. Defaults to 20." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque forward pagination cursor from a previous response's `page.next_page_token`." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record type ID" }, "name": { "type": "string", "description": "Record type name" }, "slug": { "type": "string", "description": "URL-safe record type identifier" }, "description": { "type": "string", "nullable": true, "description": "Record type description" }, "editable": { "type": "boolean", "description": "Whether records of this type can be edited after creation." }, "ttl_days": { "type": "number", "nullable": true, "description": "Records of this type are deleted this many days after their `retention_column_name` timestamp. `null` when retention is off." }, "retention_column_name": { "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT" ], "description": "Timestamp column used to age records for retention expiry. Only meaningful when `ttl_days` is set." }, "on_limit_reached": { "type": "string", "enum": [ "REJECT", "EVICT_OLDEST" ], "description": "Behaviour when the record limit is reached: `REJECT` blocks new records, `EVICT_OLDEST` deletes the oldest to make room." }, "custom_records_limit": { "type": "integer", "nullable": true, "description": "The custom per-type record limit, or `null` when no per-type limit is set — the tenant-wide ceiling then applies and is reflected in `effective_max_records`." }, "effective_max_records": { "type": "integer", "nullable": true, "description": "The record limit actually enforced: the custom limit clamped to the tenant ceiling, or the tenant ceiling when no custom limit is set. `null` when the tenant sets no ceiling and no custom limit applies." }, "has_custom_limit": { "type": "boolean", "description": "Whether a custom limit below the tenant ceiling is in force for this type." }, "relationships": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "integer", "description": "Team ID" } }, "nullable": true, "description": "Owning team, or null for a global record type." } } }, "created_at": { "type": "string", "description": "ISO-8601 creation timestamp (UTC)." }, "updated_at": { "type": "string", "description": "ISO-8601 last-updated timestamp (UTC)." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Field ID" }, "name": { "type": "string", "description": "Field name" }, "slug": { "type": "string", "description": "URL-safe field identifier" }, "result_type": { "type": "string", "description": "Field type: TEXT, TEXT_ENUM, TEXT_REGEX, EMAIL, URL, IP_ADDRESS, NUMBER, BOOLEAN, TIMESTAMP, JSON, or ARTIFACT." }, "fixed_values": { "type": "array", "items": { "type": "string" }, "description": "Allowed values for a TEXT_ENUM field; empty otherwise." }, "description": { "type": "string", "nullable": true, "description": "Field description" }, "config": { "type": "object", "properties": { "regex": { "type": "string", "nullable": true, "description": "Regular expression for a TEXT_REGEX field." }, "disable_hyperlink": { "type": "boolean", "description": "Displays URL field values as plain text when true." } }, "description": "Type-specific field configuration; empty when not configured." } } }, "description": "Custom fields defined on this record type, ordered by id." } } } }, "page": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Opaque forward cursor; present only when another page exists. Pass it back as `after`." } }, "description": "Pagination cursor. Empty on the last page." } } }, "example": { "data": [ { "id": 42, "name": "Alerts", "slug": "alerts", "description": "Firewall alerts", "editable": false, "ttl_days": 30.0, "retention_column_name": "CREATED_AT", "on_limit_reached": "REJECT", "custom_records_limit": 100000, "effective_max_records": 100000, "has_custom_limit": true, "relationships": { "team": { "id": 7 } }, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-02T00:00:00Z", "fields": [ { "id": 101, "name": "Severity", "slug": "severity", "result_type": "TEXT_ENUM", "fixed_values": [ "low", "high" ], "description": "Alert severity" } ] } ], "page": {} } } } } } } }, "/api/v2/record_types/{id}": { "get": { "summary": "Get a record type", "operationId": "get_api_v2_record_types_by_id", "description": "Fetch a single record type and its custom fields by numeric id.", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record type ID." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record type ID" }, "name": { "type": "string", "description": "Record type name" }, "slug": { "type": "string", "description": "URL-safe record type identifier" }, "description": { "type": "string", "nullable": true, "description": "Record type description" }, "editable": { "type": "boolean", "description": "Whether records of this type can be edited after creation." }, "ttl_days": { "type": "number", "nullable": true, "description": "Records of this type are deleted this many days after their `retention_column_name` timestamp. `null` when retention is off." }, "retention_column_name": { "type": "string", "enum": [ "CREATED_AT", "UPDATED_AT" ], "description": "Timestamp column used to age records for retention expiry. Only meaningful when `ttl_days` is set." }, "on_limit_reached": { "type": "string", "enum": [ "REJECT", "EVICT_OLDEST" ], "description": "Behaviour when the record limit is reached: `REJECT` blocks new records, `EVICT_OLDEST` deletes the oldest to make room." }, "custom_records_limit": { "type": "integer", "nullable": true, "description": "The custom per-type record limit, or `null` when no per-type limit is set — the tenant-wide ceiling then applies and is reflected in `effective_max_records`." }, "effective_max_records": { "type": "integer", "nullable": true, "description": "The record limit actually enforced: the custom limit clamped to the tenant ceiling, or the tenant ceiling when no custom limit is set. `null` when the tenant sets no ceiling and no custom limit applies." }, "has_custom_limit": { "type": "boolean", "description": "Whether a custom limit below the tenant ceiling is in force for this type." }, "relationships": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "integer", "description": "Team ID" } }, "nullable": true, "description": "Owning team, or null for a global record type." } } }, "created_at": { "type": "string", "description": "ISO-8601 creation timestamp (UTC)." }, "updated_at": { "type": "string", "description": "ISO-8601 last-updated timestamp (UTC)." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Field ID" }, "name": { "type": "string", "description": "Field name" }, "slug": { "type": "string", "description": "URL-safe field identifier" }, "result_type": { "type": "string", "description": "Field type: TEXT, TEXT_ENUM, TEXT_REGEX, EMAIL, URL, IP_ADDRESS, NUMBER, BOOLEAN, TIMESTAMP, JSON, or ARTIFACT." }, "fixed_values": { "type": "array", "items": { "type": "string" }, "description": "Allowed values for a TEXT_ENUM field; empty otherwise." }, "description": { "type": "string", "nullable": true, "description": "Field description" }, "config": { "type": "object", "properties": { "regex": { "type": "string", "nullable": true, "description": "Regular expression for a TEXT_REGEX field." }, "disable_hyperlink": { "type": "boolean", "description": "Displays URL field values as plain text when true." } }, "description": "Type-specific field configuration; empty when not configured." } } }, "description": "Custom fields defined on this record type, ordered by id." } } } } }, "example": { "data": { "id": 42, "name": "Alerts", "slug": "alerts", "description": "Firewall alerts", "editable": false, "ttl_days": 30.0, "retention_column_name": "CREATED_AT", "on_limit_reached": "REJECT", "custom_records_limit": 100000, "effective_max_records": 100000, "has_custom_limit": true, "relationships": { "team": { "id": 7 } }, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-02T00:00:00Z", "fields": [ { "id": 101, "name": "Severity", "slug": "severity", "result_type": "TEXT_ENUM", "fixed_values": [ "low", "high" ], "description": "Alert severity" } ] } } } } } } } }, "/api/v2/records/{id}": { "get": { "summary": "Get a record", "operationId": "get_api_v2_records_by_id", "description": "Fetch a single record by numeric id. Supports sparse fieldsets, inline expansion of artifact fields, and embedding related resources (`record_type`, `child_records`, `cases`).", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record ID." }, { "name": "record_type_id", "in": "query", "schema": { "type": "integer" }, "description": "Optional scope; a record whose type does not match returns 404." }, { "name": "include[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "record_type", "parent_record", "child_records", "child_record_ids", "cases" ] } }, "description": "Relationships to embed. `record_type` embeds a body under `included`; `parent_record` always rides in `relationships` as a bare ref. The to-many embeds `child_records` and `cases` return bare arrays under `included`, each capped at 20; when more exist, `relationships..truncated` is true - page the rest via the nested `child_records`/`cases` routes. `child_record_ids` adds `relationships.child_record_ids` (an IDs-only list, same cap and `truncated` flag, paged via the nested `child_record_ids` route): it exposes every direct child's ID - including children whose contents the caller cannot read - without returning their fields or bodies." }, { "name": "expand[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Artifact fields to hydrate inline, e.g. `fields.payload` or `fields.*`." }, { "name": "fields", "in": "query", "schema": { "type": "object" }, "description": "Sparse fieldset, e.g. `{ \"record\": \"status,severity\" }`. Matching is insensitive to case and separators." }, { "name": "timezone", "in": "query", "schema": { "type": "string" }, "description": "IANA timezone for timestamp output. Defaults to UTC." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record ID" }, "fields": { "type": "object", "description": "Field values keyed by field slug (`field_` when two fields share a slug). Scalar fields hold their typed value; TIMESTAMP fields are ISO-8601 strings; an unexpanded artifact-backed field (JSON or ARTIFACT) is returned as a handle `{ \"expandable\": true, \"href\": \"/api/v2/records//fields/\" }`." }, "relationships": { "type": "object", "properties": { "record_type": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record type ID" } } }, "parent_record": { "type": "object", "properties": { "id": { "type": "integer", "description": "Parent record ID" } }, "nullable": true, "description": "The parent record, or null when the record has no parent." } } }, "created_at": { "type": "string", "description": "ISO-8601 creation timestamp (UTC unless a `timezone` is supplied)." }, "updated_at": { "type": "string", "description": "ISO-8601 last-updated timestamp (UTC unless a `timezone` is supplied)." } } }, "field_ids": { "type": "object", "description": "Map of each returned field's slug key to its immutable field id." }, "included": { "type": "object", "properties": { "child_records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record ID" }, "fields": { "type": "object", "description": "Field values keyed by field slug (`field_` when two fields share a slug). Scalar fields hold their typed value; TIMESTAMP fields are ISO-8601 strings; an unexpanded artifact-backed field (JSON or ARTIFACT) is returned as a handle `{ \"expandable\": true, \"href\": \"/api/v2/records//fields/\" }`." }, "relationships": { "type": "object", "properties": { "record_type": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record type ID" } } }, "parent_record": { "type": "object", "properties": { "id": { "type": "integer", "description": "Parent record ID" } }, "nullable": true, "description": "The parent record, or null when the record has no parent." } } }, "created_at": { "type": "string", "description": "ISO-8601 creation timestamp (UTC unless a `timezone` is supplied)." }, "updated_at": { "type": "string", "description": "ISO-8601 last-updated timestamp (UTC unless a `timezone` is supplied)." } } } }, "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Public case number." }, "name": { "type": "string", "description": "Case name" }, "status": { "type": "string", "description": "Case status" }, "priority": { "type": "string", "description": "Case severity" }, "linked_at": { "type": "string", "description": "When the case was linked to this record (ISO-8601)." }, "created_at": { "type": "string", "description": "ISO-8601 case creation timestamp" }, "updated_at": { "type": "string", "description": "ISO-8601 case last-updated timestamp" } } } } }, "description": "Present only when `include` is used. `record_type` (when included) is a one-element array of `{ id, name, slug }`; `child_records` and `cases` are bare arrays whose `truncated` flag lives in the matching `relationships` entry." } } }, "example": { "data": { "id": 555, "fields": { "status": "open", "payload": { "expandable": true, "href": "/api/v2/records/555/fields/103" } }, "relationships": { "record_type": { "id": 42 }, "parent_record": null, "child_records": { "truncated": false }, "child_record_ids": { "ids": [ 556 ], "truncated": false }, "cases": { "truncated": false } }, "created_at": "2026-07-02T00:00:00Z", "updated_at": "2026-07-02T00:00:00Z" }, "field_ids": { "status": 101, "payload": 103 }, "included": { "child_records": [ { "id": 556, "fields": { "status": "closed" }, "relationships": { "record_type": { "id": 42 }, "parent_record": { "id": 555 } }, "created_at": "2026-07-02T00:00:00Z", "updated_at": "2026-07-02T00:00:00Z" } ], "cases": [ { "id": 123, "name": "Investigation", "status": "open", "priority": "high", "linked_at": "2026-07-05T09:00:00Z", "created_at": "2026-07-03T00:00:00Z", "updated_at": "2026-07-03T00:00:00Z" } ] } } } } } } } }, "/api/v2/records/{id}/child_record_ids": { "get": { "summary": "List a record's child record IDs", "operationId": "get_api_v2_records_by_id_child_record_ids", "description": "List the IDs of the records whose parent is the given record, newest first. Unlike `child_records`, this exposes every direct child's ID - including children whose contents the caller cannot read - and never returns their fields or bodies. Results are keyset-paginated.", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The parent record ID." }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Page size, 1-500. Defaults to 20." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque forward pagination cursor from a previous response's `page.next_page_token`." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "integer" }, "description": "Child record IDs." }, "page": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Opaque forward cursor; present only when another page exists. Pass it back as `after`." } }, "description": "Pagination cursor. Empty on the last page." } } }, "example": { "data": [ 556, 557 ], "page": {} } } } } } } }, "/api/v2/records/{id}/child_records": { "get": { "summary": "List a record's child records", "operationId": "get_api_v2_records_by_id_child_records", "description": "List the records whose parent is the given record, newest first. Results are keyset-paginated.", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The parent record ID." }, { "name": "timezone", "in": "query", "schema": { "type": "string" }, "description": "IANA timezone for timestamp output. Defaults to UTC." }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Page size, 1-500. Defaults to 20." }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque forward pagination cursor from a previous response's `page.next_page_token`." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record ID" }, "fields": { "type": "object", "description": "Field values keyed by field slug (`field_` when two fields share a slug). Scalar fields hold their typed value; TIMESTAMP fields are ISO-8601 strings; an unexpanded artifact-backed field (JSON or ARTIFACT) is returned as a handle `{ \"expandable\": true, \"href\": \"/api/v2/records//fields/\" }`." }, "relationships": { "type": "object", "properties": { "record_type": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record type ID" } } }, "parent_record": { "type": "object", "properties": { "id": { "type": "integer", "description": "Parent record ID" } }, "nullable": true, "description": "The parent record, or null when the record has no parent." } } }, "created_at": { "type": "string", "description": "ISO-8601 creation timestamp (UTC unless a `timezone` is supplied)." }, "updated_at": { "type": "string", "description": "ISO-8601 last-updated timestamp (UTC unless a `timezone` is supplied)." } } } }, "page": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Opaque forward cursor; present only when another page exists. Pass it back as `after`." } }, "description": "Pagination cursor. Empty on the last page." } } }, "example": { "data": [ { "id": 556, "fields": { "status": "closed" }, "relationships": { "record_type": { "id": 42 }, "parent_record": { "id": 555 } }, "created_at": "2026-07-02T00:00:00Z", "updated_at": "2026-07-02T00:00:00Z" } ], "page": {} } } } } } } }, "/api/v2/records/{id}/fields/{field}": { "get": { "summary": "Get a record field", "operationId": "get_api_v2_records_by_id_fields_by_field", "description": "Fetch the full value of a single artifact-backed field (JSON or ARTIFACT) - the dereference target of the `{ expandable, href }` handle returned inline by the record endpoints. The value is returned unwrapped, not inside a JSON envelope. JSON fields are normalized to their canonical encoding (matching inline expansion); text/artifact fields are returned verbatim.", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record ID." }, { "name": "field", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The field id or name/slug." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "text", "txt", "plain" ] }, "description": "Override the response content type. Defaults to `json` for JSON fields and `text` for text artifacts." } ], "responses": { "200": { "description": "The field value. JSON fields (or `format=json`) are returned as `application/json`, normalized to their canonical encoding; text/artifact fields (or `format=text`) as `text/plain`, returned verbatim. A stored null value is `null` (JSON) or an empty body (text)." } } } }, "/api/v2/records/aggregate": { "post": { "summary": "Aggregate records", "operationId": "post_api_v2_records_aggregate", "description": "Run a grouped aggregation query over records of a single record type - counts, sums, averages, and more, optionally grouped by up to two fields. Prefer this over paging through search and aggregating client-side. Despite the POST verb this is a read; the query travels in the body.", "tags": [ "Records" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_type_id": { "type": "integer", "description": "Numeric record type id. Takes precedence when `record_type_name` is also provided." }, "record_type_name": { "type": "string", "description": "Record type name or slug. Used when `record_type_id` is omitted." }, "aggregations": { "type": "array", "items": { "type": "object" }, "description": "1-5 aggregations, each `{ fn, field_id? | field_name?, alias? }`. `fn` is COUNT, SUM, AVG, MIN, MAX, or MEDIAN; all except COUNT require a NUMBER field. `field_name` matches a field name or slug; matching is insensitive to case and separators. `alias` names the output column." }, "group_by": { "type": "array", "items": { "type": "object" }, "description": "0-2 groupings, each `{ field_id | field_name, date_trunc? }`. `field_name` matches a field name or slug; matching is insensitive to case and separators. `date_trunc` (hour, day, week, month, year) applies to TIMESTAMP fields." }, "filter": { "type": "object", "description": "Same AND-only filter tree as search (max 50 nodes). A single condition or an `{ op: \"AND\", nodes: [...] }` group." }, "time_range": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "updated_at" ], "description": "Timestamp column to filter. Defaults to `created_at`." }, "rolling_date_range": { "type": "string", "description": "A rolling preset name (e.g. TODAY)." }, "range_start": { "type": "string", "description": "Inclusive ISO-8601 lower bound." }, "range_end": { "type": "string", "description": "Inclusive ISO-8601 upper bound." } } }, "description": "Restrict which records are aggregated to up to two timestamp windows, ANDed together, at most one per `field`. Each window's `field` picks the column (`created_at` default, or `updated_at`); supply either a `rolling_date_range` preset or `range_start`/`range_end` bounds, not both." }, "order_by": { "type": "array", "items": { "type": "object" }, "description": "At most one `{ field_id | field_name | alias, direction }` naming a group-by field or an aggregation alias." }, "parent_ids": { "type": "array", "items": { "type": "integer" }, "description": "Restrict to records under these parents (max 100)." }, "timezone": { "type": "string", "description": "IANA timezone applied to `date_trunc` buckets and time-range parsing. Defaults to UTC." }, "limit": { "type": "integer", "description": "Maximum rows to return, 1-500." } }, "required": [ "aggregations" ] }, "example": { "record_type_id": 42, "aggregations": [ { "fn": "COUNT", "alias": "total" } ], "group_by": [ { "field_name": "Status" } ], "order_by": [ { "alias": "total", "direction": "DESC" } ], "limit": 100 } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" }, "description": "One object per result row, keyed by group-by field name and aggregation alias. Numeric aggregate values are returned as strings; COUNT is an integer." }, "meta": { "type": "object", "properties": { "row_count": { "type": "integer", "description": "Number of rows returned." }, "truncated": { "type": "boolean", "description": "True when more rows existed than the row cap returned." }, "columns": { "type": "object", "properties": { "group_by": { "type": "array", "items": { "type": "string" } }, "aggregations": { "type": "array", "items": { "type": "string" } } }, "description": "Ordered output column keys." } } } } }, "example": { "rows": [ { "Status": "open", "total": 2 }, { "Status": "closed", "total": 1 } ], "meta": { "row_count": 2, "truncated": false, "columns": { "group_by": [ "Status" ], "aggregations": [ "total" ] } } } } } } } } }, "/api/v2/records/search": { "post": { "summary": "Search records", "operationId": "post_api_v2_records_search", "description": "List and filter records of a single record type. Despite the POST verb this is a read - the criteria travel in the body. Supports filtering, sorting, sparse fieldsets, relationship includes, time-range narrowing, and keyset pagination.", "tags": [ "Records" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_type_id": { "type": "integer", "description": "Numeric record type id. Takes precedence when `record_type_name` is also provided." }, "record_type_name": { "type": "string", "description": "Record type name or slug. Used when `record_type_id` is omitted." }, "filter": { "type": "object", "description": "Filter tree: a single condition `{ field_id | field_name, operator, value }`, or an AND group `{ \"op\": \"AND\", \"nodes\": [...] }` (max depth 4, 50 nodes). Only AND is supported. `field_name` matches a field name or slug; matching is insensitive to case and separators. Available operators depend on the field type (e.g. TEXT: EQUAL, CONTAINS, IS_ANY_OF; NUMBER: GREATER_THAN, LESS_THAN; TIMESTAMP: GREATER_THAN, LESS_THAN)." }, "sort": { "type": "array", "items": { "type": "object" }, "description": "Ordered sort keys, each `{ field_id | field_name, direction }` where direction is ASC or DESC. `field_name` matches a field name or slug; matching is insensitive to case and separators. `created_at` is accepted as a field name." }, "fields": { "type": "object", "description": "Sparse fieldset, e.g. `{ \"record\": \"status,severity\" }`. Matching is insensitive to case and separators. Omit for all fields." }, "include": { "type": "array", "items": { "type": "string", "enum": [ "record_type", "parent_record" ] }, "description": "To-one relationships to embed. `record_type` is embedded under `included`; `parent_record` rides in each record's `relationships`." }, "ids": { "type": "array", "items": { "type": "integer" }, "description": "Hydrate specific record ids (max 500). Cannot be combined with `after`." }, "time_range": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "created_at", "updated_at" ], "description": "Timestamp column to filter. Defaults to `created_at`." }, "rolling_date_range": { "type": "string", "description": "A rolling preset name (e.g. TODAY)." }, "range_start": { "type": "string", "description": "Inclusive ISO-8601 lower bound." }, "range_end": { "type": "string", "description": "Inclusive ISO-8601 upper bound." } } }, "description": "Up to two timestamp windows, ANDed together, at most one per `field`. Each window's `field` picks the column (`created_at` default, or `updated_at`); supply either a `rolling_date_range` preset or `range_start`/`range_end` bounds, not both." }, "timezone": { "type": "string", "description": "IANA timezone applied to time-range presets and timestamp output. Defaults to UTC." }, "limit": { "type": "integer", "description": "Page size, 1-500. Defaults to 20." }, "after": { "type": "string", "description": "Opaque forward pagination cursor from `page.next_page_token`." }, "include_total": { "type": "boolean", "description": "When true, include `page.total`. Defaults to false." }, "test_mode": { "type": "boolean", "description": "When true, search test records instead of live records. Requires change control. Defaults to false." } } }, "example": { "record_type_id": 42, "filter": { "field_name": "Status", "operator": "EQUAL", "value": "open" }, "sort": [ { "field_name": "Severity", "direction": "DESC" } ], "include": [ "record_type" ], "include_total": true, "limit": 20 } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record ID" }, "fields": { "type": "object", "description": "Field values keyed by field slug (`field_` when two fields share a slug). Scalar fields hold their typed value; TIMESTAMP fields are ISO-8601 strings; an unexpanded artifact-backed field (JSON or ARTIFACT) is returned as a handle `{ \"expandable\": true, \"href\": \"/api/v2/records//fields/\" }`." }, "relationships": { "type": "object", "properties": { "record_type": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record type ID" } } }, "parent_record": { "type": "object", "properties": { "id": { "type": "integer", "description": "Parent record ID" } }, "nullable": true, "description": "The parent record, or null when the record has no parent." } } }, "created_at": { "type": "string", "description": "ISO-8601 creation timestamp (UTC unless a `timezone` is supplied)." }, "updated_at": { "type": "string", "description": "ISO-8601 last-updated timestamp (UTC unless a `timezone` is supplied)." } } } }, "field_ids": { "type": "object", "description": "Map of each returned field's slug key to its immutable field id." }, "included": { "type": "object", "description": "Present only when `include` is used. `record_type` is a one-element array of `{ id, name, slug }`." }, "page": { "type": "object", "properties": { "next_page_token": { "type": "string", "description": "Opaque forward cursor; present only when another page exists." }, "total": { "type": "integer", "description": "Total matching records; present only when `include_total` is true." } }, "description": "Pagination cursor and optional total. Empty on the last page." }, "applied": { "type": "object", "properties": { "filter": { "type": "object", "nullable": true, "description": "The interpreted filter as a single condition, an `{ op: \"AND\", nodes: [...] }` group, or null." }, "sort": { "type": "array", "items": { "type": "object" }, "description": "`{ field_id, direction }` entries, in priority order." } }, "description": "Echoes the filter and sort actually applied." } } }, "example": { "data": [ { "id": 555, "fields": { "status": "open", "severity": "high", "payload": { "expandable": true, "href": "/api/v2/records/555/fields/103" } }, "relationships": { "record_type": { "id": 42 }, "parent_record": null }, "created_at": "2026-07-02T00:00:00Z", "updated_at": "2026-07-02T00:00:00Z" } ], "field_ids": { "status": 101, "severity": 102, "payload": 103 }, "included": { "record_type": [ { "id": 42, "name": "Alerts", "slug": "alerts" } ] }, "page": { "next_page_token": "example-next-page-token", "total": 1 }, "applied": { "filter": { "field_id": 101, "operator": "EQUAL", "value": "open" }, "sort": [ { "field_id": 102, "direction": "DESC" } ] } } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-User-Token", "description": "A Tines API key. Personal, service, team, and tenant owner keys are all accepted; the key's own access determines which resources the request can reach, and a key without access to a resource receives a 404. SCIM endpoints require a tenant owner key." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Tines API key. Personal, service, team, and tenant owner keys are all accepted; the key's own access determines which resources the request can reach, and a key without access to a resource receives a 404. SCIM endpoints require a tenant owner key." } }, "schemas": { "PaginationMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" } } }, "user": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "User ID" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "email": { "type": "string", "description": "Email address" }, "avatar_url": { "type": "string", "nullable": true, "description": "Avatar URL" }, "is_service_account": { "type": "boolean", "description": "Whether this is a service account" } }, "description": "A Tines user" }, "case": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "name": { "type": "string", "description": "Case name" }, "description": { "type": "string", "nullable": true, "description": "Case description" }, "status": { "type": "string", "description": "Case status (OPEN, CLOSED)" }, "sub_status": { "type": "object", "nullable": true, "description": "Sub-status with id and name" }, "priority": { "type": "string", "description": "Priority level" }, "url": { "type": "string", "description": "Case URL" }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary metadata object" }, "author": { "$ref": "#/components/schemas/user" }, "opened_by": { "$ref": "#/components/schemas/user" }, "resolved_by": { "$ref": "#/components/schemas/user" }, "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/user" } }, "tags": { "type": "array", "items": { "type": "object" }, "description": "Tags" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Associated records" }, "activities": { "type": "array", "items": { "$ref": "#/components/schemas/activity" } }, "team": { "type": "object", "description": "Team the case belongs to" }, "sla": { "type": "object", "nullable": true, "description": "SLA status" }, "slas": { "type": "array", "items": { "type": "object" }, "description": "SLA statuses" }, "actions": { "type": "array", "items": { "type": "object" }, "description": "Case actions" }, "linked_cases": { "type": "array", "items": { "$ref": "#/components/schemas/linked_case" } }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Closure conditions" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/field" } }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "Case blocks" }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" } }, "opened_at": { "type": "string", "nullable": true, "description": "When the case was opened" }, "resolved_at": { "type": "string", "nullable": true, "description": "When the case was resolved" }, "created_at": { "type": "string", "description": "When the case was created" }, "updated_at": { "type": "string", "description": "When the case was last updated" } }, "description": "A case" }, "activity": { "type": "object", "properties": { "id": { "type": "integer", "description": "Activity ID" }, "activity_type": { "type": "string", "description": "Type of activity" }, "value": { "type": "string", "nullable": true, "description": "Activity content" }, "file": { "type": "object", "nullable": true, "description": "Attached file with filename and url" }, "created_at": { "type": "string", "description": "When the activity was created" }, "user": { "$ref": "#/components/schemas/user" }, "reactions": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Emoji reactions" } }, "description": "A case activity or comment" }, "action": { "type": "object", "properties": { "id": { "type": "integer", "description": "Action ID" }, "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "nullable": true, "description": "Action label" }, "story_name": { "type": "string", "nullable": true, "description": "Associated story name" }, "page_emoji": { "type": "string", "nullable": true, "description": "Page emoji" }, "story_emoji": { "type": "string", "nullable": true, "description": "Story emoji" }, "action_type": { "type": "string", "description": "Action type (e.g. webhook, page)" }, "action_text": { "type": "string", "nullable": true, "description": "Button text" }, "query_param_key": { "type": "string", "nullable": true, "description": "Query parameter key" }, "query_param_value": { "type": "string", "nullable": true, "description": "Query parameter value" }, "query_params": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Additional query parameters" }, "created_at": { "type": "string", "description": "When the action was created" }, "updated_at": { "type": "string", "description": "When the action was last updated" } }, "description": "A case action (button/trigger)" }, "block": { "type": "object", "properties": { "id": { "type": "integer", "description": "Block ID" }, "title": { "type": "string", "nullable": true, "description": "Block title" }, "slug": { "type": "string", "nullable": true, "description": "Block slug identifier" }, "block_type": { "type": "string", "description": "Block type (note, html, file, block_group)" }, "color": { "type": "string", "enum": [ "primary", "gold", "magenta", "green", "blue", "red", "mint", "indigo", "white" ], "description": "Block color, only present on note, html, file, and block_group blocks" }, "position": { "type": "integer", "description": "Display position" }, "hidden": { "type": "boolean", "description": "Whether the block is hidden" }, "block_group_id": { "type": "integer", "nullable": true, "description": "Parent block group ID" }, "elements": { "type": "array", "items": { "$ref": "#/components/schemas/block_element" } }, "created_at": { "type": "string", "description": "When the block was created" }, "updated_at": { "type": "string", "description": "When the block was last updated" } }, "description": "A case block" }, "block_element": { "type": "object", "properties": { "element_id": { "type": "integer", "description": "Element ID" }, "id": { "type": "integer", "description": "Blockable content ID" }, "element_type": { "type": "string", "description": "Element type (note, html, file)" }, "content": { "type": "string", "nullable": true, "description": "Element content" }, "note_type": { "type": "string", "nullable": true, "description": "Note type" }, "color": { "type": "string", "nullable": true, "description": "Color" }, "sensitive": { "type": "boolean", "description": "Whether the content is sensitive" }, "file": { "type": "object", "nullable": true, "description": "Attached file" }, "author": { "$ref": "#/components/schemas/user" }, "created_at": { "type": "string", "description": "When the element was created" }, "updated_at": { "type": "string", "description": "When the element was last updated" } }, "description": "An element within a case block" }, "field": { "type": "object", "properties": { "id": { "type": "integer", "description": "Field value ID" }, "value": { "type": "string", "nullable": true, "description": "Field value" }, "case_input": { "type": "object", "description": "Field definition (id, key, name, validation_type, validation_options)" } }, "description": "A case field value" }, "linked_case": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Linked case ID" }, "name": { "type": "string", "description": "Linked case name" } }, "description": "A linked case reference" }, "note": { "type": "object", "properties": { "id": { "type": "integer", "description": "Note ID" }, "title": { "type": "string", "nullable": true, "description": "Note title" }, "content": { "type": "string", "nullable": true, "description": "Note content" }, "color": { "type": "string", "nullable": true, "description": "Note color" }, "sensitive": { "type": "boolean", "description": "Whether the note is sensitive" }, "hidden": { "type": "boolean", "description": "Whether the note is hidden" }, "author": { "$ref": "#/components/schemas/user" }, "created_at": { "type": "string", "description": "When the note was created" }, "updated_at": { "type": "string", "description": "When the note was last updated" } }, "description": "A case note" }, "record": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record result set ID" }, "record_type": { "type": "object", "description": "Record type with id and name" }, "results": { "type": "array", "items": { "type": "object" }, "description": "Record results with id, name, and value" }, "created_at": { "type": "string", "description": "When the record was created" }, "linked_at": { "type": "string", "nullable": true, "description": "When the record was linked to the case; null for child records fetched via `parent_record_id`" } }, "description": "A case record result set" }, "subscriber": { "type": "object", "properties": { "id": { "type": "integer", "description": "Subscriber ID" }, "user": { "type": "object", "description": "Subscribed user (user_id, first_name, last_name, email, avatar_url)" } }, "description": "A case subscriber" }, "task": { "type": "object", "properties": { "id": { "type": "integer", "description": "Task ID" }, "description": { "type": "string", "description": "Task description" }, "completed": { "type": "boolean", "description": "Whether the task is completed" }, "created_at": { "type": "string", "description": "When the task was created" }, "updated_at": { "type": "string", "description": "When the task was last updated" }, "assignees": { "type": "array", "items": { "type": "object" }, "description": "Assigned users (id, email, first_name, last_name)" } }, "description": "A case task" }, "metadata": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "metadata": { "type": "object", "description": "Metadata key-value pairs" } }, "description": "Case metadata" }, "case_v1": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "name": { "type": "string", "description": "Case name" }, "description": { "type": "string", "nullable": true, "description": "Case description" }, "status": { "type": "string", "description": "Case status (OPEN, CLOSED)" }, "priority": { "type": "string", "description": "Priority level" }, "url": { "type": "string", "description": "Case URL" }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary metadata object" }, "author": { "$ref": "#/components/schemas/user" }, "opened_by": { "$ref": "#/components/schemas/user" }, "resolved_by": { "$ref": "#/components/schemas/user" }, "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/user" } }, "tags": { "type": "array", "items": { "type": "object" }, "description": "Tags with id and name" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/record" } }, "team_case_actions": { "type": "array", "items": { "type": "object" }, "description": "Case activities (id, action, value, user, created_at)" }, "team": { "type": "object", "description": "Team with id and name" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Buttons (id, button_type, url, label, button_text)" }, "linked_cases": { "type": "array", "items": { "type": "object" }, "description": "Linked cases (case_id)" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Closure conditions (name, formula)" }, "opened_at": { "type": "string", "nullable": true, "description": "When the case was opened" }, "resolved_at": { "type": "string", "nullable": true, "description": "When the case was resolved" }, "created_at": { "type": "string", "description": "When the case was created" }, "updated_at": { "type": "string", "description": "When the case was last updated" } }, "description": "A case (v1 API shape)" }, "action_v1": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "id": { "type": "integer", "description": "Action ID" }, "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "story_name": { "type": "string", "nullable": true, "description": "Associated story name" }, "page_emoji": { "type": "string", "nullable": true, "description": "Page emoji" }, "story_emoji": { "type": "string", "nullable": true, "description": "Story emoji" }, "button_type": { "type": "string", "description": "Action type (e.g. webhook, page)" }, "button_text": { "type": "string", "nullable": true, "description": "Action text" }, "created_at": { "type": "string", "description": "When the action was created" }, "updated_at": { "type": "string", "description": "When the action was last updated" } }, "description": "A case action (v1 API shape)" }, "activity_v1": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "id": { "type": "integer", "description": "Activity ID" }, "action": { "type": "string", "description": "Type of activity" }, "value": { "type": "string", "nullable": true, "description": "Activity content" }, "user": { "$ref": "#/components/schemas/user" }, "reactions": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Emoji reactions with emoji and reactants" } }, "description": "A case comment or activity (v1 API shape)" }, "record_v1": { "type": "object", "properties": { "id": { "type": "integer", "description": "Record result set ID" }, "record_type": { "type": "object", "description": "Record type with id and name" }, "records": { "type": "array", "items": { "type": "object" }, "description": "Record results with id, name, and value" }, "created_at": { "type": "string", "description": "When the record was created" } }, "description": "A case record result set (v1 API shape)" }, "record_result_v1": { "type": "object", "properties": { "id": { "type": "integer", "description": "The record ID" }, "updated_at": { "type": "string", "description": "When the record was last updated" }, "case_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of cases the record is linked to" }, "parent_record": { "type": "object", "nullable": true, "description": "The parent record with its id, or null if the record has no parent" } }, "description": "A single record. Alongside these properties, each custom field is included as a top-level key mapping the field name to its value." }, "record_type": { "type": "object", "properties": { "id": { "type": "integer", "description": "The record type ID" }, "name": { "type": "string", "description": "The record type name" }, "description": { "type": "string", "nullable": true, "description": "A short description of the record type" }, "team_id": { "type": "integer", "description": "ID of the team the record type belongs to" }, "editable": { "type": "boolean", "description": "Whether records for this record type are editable" }, "ttl_days": { "type": "number", "nullable": true, "description": "Records of this type are deleted after this number of days" }, "retention_column_name": { "type": "string", "nullable": true, "description": "Timestamp column used to determine record age for TTL expiry (CREATED_AT or UPDATED_AT)" }, "on_limit_reached": { "type": "string", "description": "Behavior when the per-type record limit is reached (REJECT or EVICT_OLDEST)" }, "max_records_limit": { "type": "integer", "nullable": true, "description": "Custom per-record-type record limit, or null when the tenant default applies" }, "record_fields": { "type": "array", "items": { "type": "object" }, "description": "The custom record fields defined by the user" }, "default_record_fields": { "type": "array", "items": { "type": "object" }, "description": "The built-in default record fields" } }, "description": "A record type — the schema defining a set of records" }, "case_template": { "type": "object", "properties": { "id": { "type": "integer", "description": "Case template ID" }, "name": { "type": "string", "description": "Template name" }, "emoji": { "type": "string", "nullable": true, "description": "Template emoji" }, "team": { "type": "object", "description": "Team with id and name" }, "created_at": { "type": "string", "description": "When the template was created" }, "updated_at": { "type": "string", "description": "When the template was last updated" } }, "description": "A case template" }, "case_sub_status": { "type": "object", "properties": { "id": { "type": "integer", "description": "Case status ID" }, "name": { "type": "string", "description": "Status name" }, "slug": { "type": "string", "description": "Human-readable identifier, auto-generated from the name" }, "description": { "type": "string", "nullable": true, "description": "Status description" }, "parent_status": { "type": "string", "description": "Parent status (OPEN or CLOSED)" }, "default": { "type": "boolean", "description": "Whether this is the default status for its parent status" }, "team": { "type": "object", "description": "Team the status belongs to" }, "created_at": { "type": "string", "description": "When the status was created" }, "updated_at": { "type": "string", "description": "When the status was last updated" } }, "description": "A case status" }, "skill": { "type": "object", "properties": { "name": { "type": "string", "description": "Skill name" }, "description": { "type": "string", "description": "What the skill does and when to use it. AI agents are shown only the name and description, and match a task against them to decide whether to load the skill" }, "body": { "type": "string", "description": "The full skill instructions, in markdown. Loaded only after the description matches the task at hand" }, "license": { "type": "string", "nullable": true, "description": "License the skill is distributed under" }, "compatibility": { "type": "string", "nullable": true, "description": "Free-text note on what the skill is compatible with" }, "metadata": { "type": "object", "description": "Flat map of string keys to string values, empty when none are set" }, "team_id": { "type": "integer", "description": "ID of the team that owns the skill" }, "created_at": { "type": "string", "description": "When the skill was created" }, "updated_at": { "type": "string", "description": "When the skill was last updated" } }, "description": "A skill" }, "case_input": { "type": "object", "properties": { "id": { "type": "integer", "description": "Field ID" }, "name": { "type": "string", "description": "Field name" }, "key": { "type": "string", "description": "Lookup key (slug)" }, "input_type": { "type": "string", "description": "Field type (string, number, boolean, timestamp)" }, "sensitive": { "type": "boolean", "description": "Whether the sensitive field permission is required to read or write" }, "validation_type": { "type": "string", "nullable": true, "description": "Validation type (none, options, regex)" }, "validation_options": { "type": "object", "nullable": true, "description": "Validation configuration" }, "team": { "type": "object", "description": "Team with id and name" }, "team_case_input_group": { "type": "object", "nullable": true, "description": "Group the field belongs to (name)" }, "created_at": { "type": "string", "description": "When the field was created" }, "updated_at": { "type": "string", "description": "When the field was last updated" } }, "description": "A case field definition" }, "case_input_field_value": { "type": "object", "properties": { "id": { "type": "integer", "description": "Field value ID" }, "value": { "type": "string", "nullable": true, "description": "The stored value" }, "case": { "type": "object", "description": "Case with id" }, "case_input": { "type": "object", "description": "Field definition (id, name, validation_type, validation_options)" } }, "description": "A field value for a specific case" }, "app": { "type": "object", "properties": { "id": { "type": "integer", "description": "The app ID" }, "guid": { "type": "string", "nullable": true, "description": "Unique identifier of the app" }, "name": { "type": "string", "description": "The app name" }, "description": { "type": "string", "nullable": true, "description": "A user-defined description of the app" }, "emoji": { "type": "string", "description": "The emoji associated with the app" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp representing date and time the app was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp representing date and time the app was last updated" }, "team": { "type": "object", "description": "Object containing the id and name of the team the app belongs to" }, "published_version": { "type": "object", "nullable": true, "description": "Object containing the id of the published version, or null if the app has not been published" } }, "description": "An app" }, "case_webhook": { "type": "object", "properties": { "id": { "type": "integer", "description": "Webhook ID" }, "name": { "type": "string", "nullable": true, "description": "Webhook name" }, "url": { "type": "string", "description": "Destination URL the webhook posts to" }, "version_number": { "type": "number", "description": "Payload version (1.0 or 2.0)" }, "notifications": { "type": "array", "items": { "type": "string" }, "description": "Event types that trigger the webhook" }, "team": { "type": "object", "description": "Team with id and name" } }, "description": "A case webhook" }, "story": { "type": "object", "properties": { "id": { "type": "integer", "description": "Story ID" }, "name": { "type": "string", "description": "Story name" }, "user_id": { "type": "integer", "description": "ID of the story creator" }, "description": { "type": "string", "nullable": true, "description": "User-defined description of the story" }, "keep_events_for": { "type": "integer", "description": "Event retention period in seconds" }, "disabled": { "type": "boolean", "description": "Whether the story is disabled" }, "priority": { "type": "boolean", "description": "Whether the story is high priority" }, "send_to_story_enabled": { "type": "boolean", "description": "Whether Send to Story is enabled" }, "send_to_story_access_source": { "type": "string", "description": "Where Send to Story can be used (STS, STS_AND_WORKBENCH, WORKBENCH, OFF)" }, "send_to_story_access": { "type": "string", "nullable": true, "description": "Who is allowed to send to this story (TEAM, GLOBAL, SPECIFIC_TEAMS)" }, "send_to_story_referring_story_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of stories that call this Send to Story enabled story. Only present when send_to_story_enabled is true" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Slugs of teams that can send to this story when send_to_story_access is SPECIFIC_TEAMS, otherwise empty" }, "send_to_story_timeout_enabled": { "type": "boolean", "description": "Whether a timeout is enabled for Send to Story runs" }, "send_to_story_timeout_duration_seconds": { "type": "integer", "nullable": true, "description": "Maximum time in seconds a Send to Story run may take before timing out. Only takes effect when send_to_story_timeout_enabled is true. null if no duration has been set" }, "send_to_story_skill_use_requires_confirmation": { "type": "boolean", "description": "Whether Workbench should ask for confirmation before running this story" }, "entry_agent_id": { "type": "integer", "nullable": true, "description": "ID of the entry action for this story" }, "exit_agents": { "type": "array", "items": { "type": "object" }, "description": "Objects describing exit actions for this story" }, "team_id": { "type": "integer", "description": "ID of the team to which the story belongs" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags used to classify the story" }, "guid": { "type": "string", "description": "Unique identifier of the story" }, "slug": { "type": "string", "description": "Underscored representation of the story name" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of when the story was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the story row was last updated" }, "edited_at": { "type": "string", "description": "ISO 8601 timestamp of when the story was last logically updated" }, "mode": { "type": "string", "description": "Mode of the story (LIVE or TEST)" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of the folder to which the story belongs" }, "published": { "type": "boolean", "description": "Whether the story is published" }, "change_control_enabled": { "type": "boolean", "description": "Whether change control is enabled" }, "locked": { "type": "boolean", "description": "Whether the story is locked to changes" }, "owners": { "type": "array", "items": { "type": "integer" }, "description": "IDs of users listed as owners on the story" }, "monitor_failures": { "type": "boolean", "description": "Whether monitor failures is enabled on all actions in the story" }, "actions_with_monitoring": { "type": "array", "items": { "type": "integer" }, "description": "IDs of actions with monitoring enabled" }, "recipients": { "type": "array", "items": { "type": "object" }, "description": "Monitoring recipients for the story" } }, "description": "A story" }, "story_action": { "type": "object", "properties": { "id": { "type": "integer", "description": "Action ID" }, "type": { "type": "string", "description": "Action type" }, "user_id": { "type": "integer", "description": "User ID of the action's owner" }, "options": { "type": "object", "description": "JSON options block of the action" }, "name": { "type": "string", "description": "Name of the action" }, "description": { "type": "string", "nullable": true, "description": "User-defined description of the action" }, "schedule": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Cron schedule for the action" }, "blended_events_count": { "type": "integer", "description": "Number of events the action has emitted in both TEST and LIVE mode" }, "logs_count": { "type": "integer", "description": "Number of logs the action has stored" }, "last_check_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of the action's last scheduled run" }, "last_receive_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of the last event received" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of when the action was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the action was last updated" }, "last_event_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of the last event received, updated at one-minute intervals" }, "last_error_log_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of the last error thrown by the action" }, "disabled": { "type": "boolean", "description": "Whether the action is disabled" }, "guid": { "type": "string", "description": "Unique identifier of the action" }, "group_id": { "type": "integer", "nullable": true, "description": "ID of the group to which the action belongs" }, "position": { "type": "object", "description": "XY coordinates of the action on the story diagram" }, "story_id": { "type": "integer", "description": "ID of the story to which the action belongs" }, "story_mode": { "type": "string", "description": "Mode of the story to which the action belongs (LIVE or TEST)" }, "nested_group_id": { "type": "integer", "nullable": true, "description": "ID of the group contained in the action" }, "team_id": { "type": "integer", "description": "ID of the team to which the action belongs" }, "sources": { "type": "array", "items": { "type": "integer" }, "description": "IDs of actions this action receives emitted events from" }, "receivers": { "type": "array", "items": { "type": "integer" }, "description": "IDs of actions this action emits events to" }, "monitor_failures": { "type": "boolean", "description": "Whether a notification should be sent when this action fails" }, "monitor_all_events": { "type": "boolean", "description": "Whether all events should be monitored" }, "monitor_no_events_emitted": { "type": "integer", "nullable": true, "description": "Duration in seconds; if no events are emitted in this time, a notification is sent" }, "time_saved_unit": { "type": "string", "nullable": true, "description": "Unit of time corresponding to the time saved value" }, "time_saved_value": { "type": "integer", "nullable": true, "description": "Amount of time saved" }, "page": { "type": "object", "nullable": true, "description": "Associated page, if this is a page action" }, "action_memory_contents": { "type": "object", "description": "Values the action may be holding in its memory" }, "slug": { "type": "string", "description": "Underscored representation of the action's name" }, "links_to_sources": { "type": "array", "items": { "type": "object" }, "description": "Links to source actions, including the source ID and link type" }, "links_to_receivers": { "type": "array", "items": { "type": "object" }, "description": "Links to receiver actions, including the receiver ID and link type" }, "story_run_save_setting": { "type": "object", "nullable": true, "description": "Story run save settings for this action; only present for Receive Email and Webhook agents" } }, "description": "An action (agent)" }, "story_note": { "type": "object", "properties": { "id": { "type": "integer", "description": "Note ID" }, "story_id": { "type": "integer", "description": "ID of the story to which the note belongs" }, "story_mode": { "type": "string", "description": "Mode of the story to which the note belongs (LIVE or TEST)" }, "group_id": { "type": "integer", "nullable": true, "description": "ID of the group to which the note belongs" }, "content": { "type": "string", "description": "Markdown-formatted content of the note" }, "position": { "type": "object", "description": "XY coordinates of the note on the story diagram" }, "draft_id": { "type": "integer", "nullable": true, "description": "ID of the draft to which the note belongs" }, "draft_name": { "type": "string", "nullable": true, "description": "Name of the draft to which the note belongs" } }, "description": "A note (annotation) on the storyboard" }, "template": { "type": "object", "properties": { "id": { "type": "integer", "description": "Template ID" }, "name": { "type": "string", "description": "Template name" }, "description": { "type": "string", "nullable": true, "description": "Template description" }, "agent_type": { "type": "string", "description": "Type of action associated with the template" }, "agent_options": { "type": "object", "description": "Action options" }, "vendor": { "type": "string", "nullable": true, "description": "Vendor name" }, "product": { "type": "string", "nullable": true, "description": "Product name" }, "team_id": { "type": "integer", "description": "ID of the team to which the template belongs" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of the folder containing the template, or null if not in a folder" }, "read_access": { "type": "string", "description": "Where this template can be used (TEAM, GLOBAL, SPECIFIC_TEAMS)" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Slugs of teams where this template can be used when read_access is SPECIFIC_TEAMS, otherwise empty" }, "action_inputs": { "type": "array", "items": { "type": "object" }, "description": "Input parameters for the template" } }, "description": "A private template" }, "sync_destination": { "type": "object", "properties": { "id": { "type": "integer", "description": "Sync destination ID" }, "destination_tenant_url": { "type": "string", "description": "Base URL of the destination tenant" }, "destination_team_id": { "type": "integer", "description": "ID of the destination team receiving the synced stories" }, "manual_sync_only": { "type": "boolean", "description": "Whether the sync destination only syncs on manual trigger" }, "sync_mode": { "type": "string", "enum": [ "live_readonly", "draft_editable" ], "description": "Whether source updates replace the live destination story (`live_readonly`) or create an editable draft (`draft_editable`)" }, "origin_team_id": { "type": "integer", "description": "ID of the team on the current tenant where the sync destination was created" }, "subscriptions": { "type": "array", "items": { "type": "object" }, "description": "Subscription objects (one per story), each with story, status, and error_message" } }, "description": "A sync destination" }, "story_version": { "type": "object", "properties": { "id": { "type": "integer", "description": "Version ID" }, "name": { "type": "string", "nullable": true, "description": "Name of the version" }, "description": { "type": "string", "nullable": true, "description": "Description of the version" }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of when the version was created" }, "export_file": { "type": "object", "nullable": true, "description": "Exported story contents for this version (returned when retrieving a single version)" } }, "description": "A story version" }, "story_run": { "type": "object", "properties": { "guid": { "type": "string", "description": "Unique identifier of the story run" }, "story_id": { "type": "integer", "description": "ID of the story that ran" }, "start_time": { "type": "string", "description": "ISO 8601 timestamp of when the story run started" }, "end_time": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of when the story run ended" }, "duration": { "type": "number", "nullable": true, "description": "Duration of the story run in seconds" }, "action_count": { "type": "integer", "description": "Number of actions that ran in the story run" }, "event_count": { "type": "integer", "description": "Number of events in the story run" }, "story_mode": { "type": "string", "description": "The mode of the story (LIVE or TEST)" }, "draft_id": { "type": "integer", "nullable": true, "description": "ID of the selected draft (TEST mode only)" }, "draft_name": { "type": "string", "nullable": true, "description": "Name of the selected draft (TEST mode only)" } }, "description": "A story run" }, "tag": { "type": "object", "properties": { "id": { "type": "integer", "description": "Tag ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color as a #RRGGBB hex value" }, "teams": { "type": "array", "items": { "type": "object" }, "description": "Teams the tag belongs to (id, name)" }, "created_at": { "type": "string", "description": "When the tag was created" }, "updated_at": { "type": "string", "description": "When the tag was last updated" } }, "description": "A tag" }, "audit_log": { "type": "object", "properties": { "id": { "type": "integer", "description": "Operation ID" }, "operation_name": { "type": "string", "description": "The name of the operation" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp representing the creation date and time of the log operation" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp representing the last updated date and time of the log operation" }, "inputs": { "type": "object", "nullable": true, "description": "JSON inputs passed to the operation" }, "outputs": { "type": "object", "nullable": true, "description": "JSON outputs generated by the operation" }, "request_ip": { "type": "string", "nullable": true, "description": "The IP address the operation was triggered from" }, "request_user_agent": { "type": "string", "nullable": true, "description": "The user agent the operation was triggered with" }, "tenant_id": { "type": "integer", "description": "The ID of the tenant the operation was triggered on" }, "user_id": { "type": "integer", "nullable": true, "description": "The ID of the user who triggered the operation" }, "user_email": { "type": "string", "nullable": true, "description": "The email of the user who triggered the operation" }, "user_name": { "type": "string", "nullable": true, "description": "The name of the user who triggered the operation" }, "impersonated_by": { "type": "string", "nullable": true, "description": "The email of the user who was impersonating, if the operation was performed during impersonation" }, "source": { "type": "string", "enum": [ "UI", "API", "Workbench", "AI Agent action", "Story Copilot", "App Editor", "Case Working", "Story Migration", "MCP", "App Builder MCP", "Cases MCP", "Records MCP" ], "nullable": true, "description": "The surface the operation was triggered from (null for operations recorded before sources were tracked)" }, "story_id": { "type": "integer", "nullable": true, "description": "ID of the story the operation was run on (null if there is no story)" }, "team_id": { "type": "integer", "nullable": true, "description": "ID of the team the operation belongs to (null if it does not belong to a team)" }, "team_name": { "type": "string", "nullable": true, "description": "Name of the team the operation belongs to (null if it does not belong to a team, or the team has been deleted)" } }, "description": "A record of a user operation executed on the tenant" }, "run_script_environment": { "type": "object", "properties": { "id": { "type": "integer", "description": "Environment ID" }, "name": { "type": "string", "nullable": true, "description": "Environment name" }, "description": { "type": "string", "nullable": true, "description": "Environment description" }, "environment_type": { "type": "string", "description": "The type of environment (e.g. lambda, cloud_tcr)" }, "file_size": { "type": "integer", "nullable": true, "description": "Size of the uploaded file in bytes" }, "environment_file_attached": { "type": "boolean", "description": "Whether a file is attached to the environment" }, "environment_file_filename": { "type": "string", "nullable": true, "description": "Filename of the attached file, if any" }, "storage_identifier": { "type": "string", "nullable": true, "description": "Checksum-based storage identifier used for deduplication" }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary metadata object" }, "uploaded_by": { "$ref": "#/components/schemas/run_script_environment_user" }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/team_summary" } }, "primary_team": { "$ref": "#/components/schemas/team_summary" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of when the environment was created" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the environment was last updated" }, "efs_path": { "type": "string", "nullable": true, "description": "EFS path for the extracted runtime (lambda environments only)" }, "efs_access_point_arn": { "type": "string", "nullable": true, "description": "EFS access point ARN (lambda environments only)" }, "efs_file_system_id": { "type": "string", "nullable": true, "description": "EFS file system ID (lambda environments only)" }, "runtime": { "type": "string", "nullable": true, "description": "Runtime identifier (lambda environments only)" }, "extraction_status": { "type": "string", "nullable": true, "description": "Status of runtime extraction, e.g. pending or completed (lambda environments only)" }, "extracted_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of when the runtime was extracted (lambda only)" }, "active": { "type": "boolean", "nullable": true, "description": "Whether the lambda environment is fully provisioned and ready for use (lambda only)" } }, "description": "A custom run script environment (runtime)" }, "run_script_environment_list_data": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/run_script_environment" } } }, "description": "The data payload returned when listing run script environments" }, "run_script_environment_user": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "email": { "type": "string", "description": "User email address" } }, "description": "The user who uploaded a run script environment" }, "team_summary": { "type": "object", "properties": { "id": { "type": "integer", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" } }, "description": "A team reference with id and name" }, "direct_upload_url_result": { "type": "object", "properties": { "direct_upload_url": { "type": "string", "description": "Pre-signed URL to upload the file directly to storage" }, "blob_signed_id": { "type": "string", "description": "Signed blob ID to pass back when creating the environment after uploading" }, "headers": { "type": "object", "description": "Headers that must be sent with the direct upload request" } }, "description": "Pre-signed direct upload details for a run script environment file" }, "info": { "type": "object", "properties": { "stack": { "$ref": "#/components/schemas/info_stack" } }, "description": "Information about the tenant's stack" }, "info_stack": { "type": "object", "properties": { "name": { "type": "string", "description": "The name assigned to the tenant's stack" }, "type": { "type": "string", "description": "Whether the stack is dedicated or shared" }, "region": { "type": "string", "description": "The AWS region the stack is hosted in" }, "egress_ips": { "type": "array", "items": { "type": "string" }, "description": "The origin IPs used for any request originating from the tenant" } }, "description": "Details about a tenant's stack" }, "worker_stats": { "type": "object", "properties": { "current_workers": { "type": "integer", "description": "The number of active workers" }, "max_workers": { "type": "integer", "description": "The maximum number of workers allowed" }, "queue_count": { "type": "integer", "description": "The total count of items in the queue" }, "queue_latency": { "type": "integer", "description": "The latency of the default queue in seconds" } }, "description": "Statistics about the tenant's background workers" }, "web_stats": { "type": "object", "properties": { "started_at": { "type": "string", "description": "When the web server was started" }, "backlog": { "type": "integer", "description": "The number of connections waiting to be processed by a thread" }, "running": { "type": "integer", "description": "The number of threads currently running" }, "pool_capacity": { "type": "integer", "description": "The number of requests the server can currently handle" }, "busy_threads": { "type": "integer", "description": "The number of threads currently processing a request" }, "max_threads": { "type": "integer", "description": "The maximum number of threads available" }, "requests_count": { "type": "integer", "description": "The total number of requests handled since the server started" }, "versions": { "type": "object", "description": "The Puma and Ruby versions running the web server" } }, "description": "Statistics about the Puma web server that handled the request. See https://puma.io/puma/file.stats.html for details." }, "license": { "type": "object", "properties": { "customer_name": { "type": "string", "description": "The customer name on the license" }, "unique_identifier": { "type": "string", "description": "The unique identifier for the license" }, "environment": { "type": "string", "description": "The environment the license is issued for" }, "created_at": { "type": "string", "description": "When the license was created" }, "expires_at": { "type": "string", "nullable": true, "description": "When the license expires" }, "pricing_model": { "type": "string", "description": "The pricing model for the tenant" }, "users": { "type": "integer", "description": "Maximum number of users allowed" }, "builders": { "type": "integer", "description": "Maximum number of builders allowed" }, "teams": { "type": "integer", "description": "Maximum number of teams allowed" }, "stories": { "type": "integer", "description": "Maximum number of stories allowed" }, "story_units": { "type": "integer", "description": "Maximum number of story units allowed" }, "actions": { "type": "integer", "description": "Maximum number of actions allowed" }, "tunnels": { "type": "integer", "description": "Maximum number of tunnels allowed" }, "daily_story_events": { "type": "integer", "description": "Maximum number of daily story events allowed" }, "daily_tenant_events": { "type": "integer", "description": "Maximum number of daily tenant events allowed" }, "features": { "type": "array", "items": { "type": "string" }, "description": "Feature names enabled by the license" } }, "description": "Details of the license applied to a self-hosted tenant" }, "action_egress_control_rule": { "type": "object", "properties": { "id": { "type": "integer", "description": "Rule ID" }, "ip": { "type": "string", "nullable": true, "description": "IP address or CIDR range the rule applies to" }, "fqdn": { "type": "string", "nullable": true, "description": "Fully qualified domain name the rule applies to" }, "description": { "type": "string", "nullable": true, "description": "Rule description" }, "allowed_action_types": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Action types allowed to send traffic to the destination" }, "created_at": { "type": "string", "description": "When the rule was created" }, "updated_at": { "type": "string", "description": "When the rule was last updated" } }, "description": "A rule restricting outbound traffic from actions" }, "team": { "type": "object", "properties": { "id": { "type": "integer", "description": "The team ID" }, "name": { "type": "string", "description": "The team name" }, "groups": { "type": "array", "items": { "type": "object" }, "description": "The team groups (id, name)" } }, "description": "A team" }, "team_member": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" }, "email": { "type": "string", "description": "User email" }, "is_admin": { "type": "boolean", "description": "Whether the user is an admin" }, "created_at": { "type": "string", "description": "When the user was created" }, "last_seen": { "type": "string", "nullable": true, "description": "When the user was last seen in the platform" }, "invitation_accepted": { "type": "boolean", "description": "Whether the user accepted the invitation to join the team" }, "role": { "type": "string", "description": "The user's role on the team" } }, "description": "A member of a team" }, "folder": { "type": "object", "properties": { "id": { "type": "integer", "description": "The folder ID" }, "name": { "type": "string", "description": "The folder name" }, "team_id": { "type": "integer", "description": "ID of team to which the folder belongs" }, "content_type": { "type": "string", "description": "The type of content stored in the folder (CREDENTIAL, RESOURCE, or STORY)" }, "size": { "type": "integer", "description": "The number of items in this folder" }, "parent_folder_id": { "type": "integer", "nullable": true, "description": "ID of the parent folder, or null if at the root level" } }, "description": "A folder" }, "global_resource": { "type": "object", "properties": { "id": { "type": "integer", "description": "Resource ID" }, "name": { "type": "string", "description": "Name of the resource" }, "value": { "type": "string", "description": "Value of the resource. By default a string representation; use typed_value=true for properly typed values" }, "team_id": { "type": "integer", "description": "ID of team to which the resource belongs" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of folder to which the resource belongs" }, "user_id": { "type": "integer", "description": "ID of user associated with the resource" }, "read_access": { "type": "string", "description": "Where this resource can be used (TEAM, GLOBAL, SPECIFIC_TEAMS)" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this resource can be used when read_access is SPECIFIC_TEAMS, otherwise empty" }, "slug": { "type": "string", "description": "An underscored representation of the resource name" }, "created_at": { "type": "string", "description": "When the resource was created" }, "updated_at": { "type": "string", "description": "When the resource was last updated" }, "description": { "type": "string", "description": "Description of the resource" }, "test_resource_enabled": { "type": "boolean", "description": "Whether the resource is enabled for using a test resource" }, "test_resource": { "type": "object", "nullable": true, "description": "The test resource (value, created_at, updated_at), present only when test_resource_enabled is true" }, "referencing_action_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of actions that reference the resource. Excluded when include_referencing_action_ids is false" } }, "description": "A resource" }, "user_credential": { "type": "object", "properties": { "id": { "type": "integer", "description": "Credential ID" }, "name": { "type": "string", "description": "Name of the credential" }, "mode": { "type": "string", "description": "The type of credential (TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST)" }, "team_id": { "type": "integer", "description": "ID of team to which the credential belongs" }, "folder_id": { "type": "integer", "nullable": true, "description": "ID of folder to which the credential belongs" }, "read_access": { "type": "string", "description": "Where this credential can be used (TEAM, GLOBAL, SPECIFIC_TEAMS)" }, "shared_team_slugs": { "type": "array", "items": { "type": "string" }, "description": "Teams' slugs where this credential can be used when read_access is SPECIFIC_TEAMS, otherwise empty" }, "slug": { "type": "string", "description": "An underscored representation of the credential name" }, "created_at": { "type": "string", "description": "When the credential was created" }, "updated_at": { "type": "string", "description": "When the credential was last updated" }, "description": { "type": "string", "description": "Description of the credential" }, "aws_assumed_role_external_id": { "type": "string", "nullable": true, "description": "External ID for AWS assumed role, if any" }, "aws_assumed_role_source_identity": { "type": "string", "nullable": true, "description": "Source identity supplied when assuming the AWS role, if any. Requires sts:SetSourceIdentity to be allowed in the role's trust policy, in a separate statement from the one with the sts:ExternalId condition, and, for key-based or instance-profile access, in the calling IAM principal's policy" }, "use_static_external_id": { "type": "boolean", "description": "Whether the credential uses a team-scoped static external ID (AWS credentials)" }, "aws_authentication_type": { "type": "string", "nullable": true, "description": "The AWS authentication method, if any (KEY, ROLE, INSTANCE_PROFILE)" }, "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "Domains where this credential can be used in HTTP requests" }, "metadata": { "type": "object", "description": "Key/value metadata for use in HTTP requests alongside the credential value" }, "restriction_type": { "type": "string", "description": "The restriction applied to the credential (RESTRICTED, RESTRICTED_TO_CREDENTIALS, UNRESTRICTED)" }, "test_credential_enabled": { "type": "boolean", "description": "Whether the credential is enabled for using a test credential" }, "test_credential": { "type": "object", "nullable": true, "description": "The test credential (created_at, updated_at), present only when test_credential_enabled is true" }, "owner": { "type": "object", "description": "The user who owns this credential (user_id, first_name, last_name, email)" }, "expires_at": { "type": "string", "nullable": true, "description": "When the credential will expire, or null" }, "expiry_notifications_enabled": { "type": "boolean", "description": "Whether expiry notifications are enabled" }, "credential_notification_recipient_user_ids": { "type": "array", "items": { "type": "integer" }, "description": "User IDs that will be sent credential notifications (e.g. expiry notifications)" }, "references": { "type": "array", "items": { "type": "object" }, "description": "Stories referencing this credential, grouped by story (story_id, team_id, action_ids). Only included when include_references is true" } }, "description": "A credential" }, "scim_user": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "description": "SCIM schema URIs the resource conforms to" }, "id": { "type": "string", "description": "Identifier generated by Tines" }, "externalId": { "type": "string", "nullable": true, "description": "Identifier generated by the IdP" }, "userName": { "type": "string", "description": "The username for the user. It must be the user's email" }, "name": { "$ref": "#/components/schemas/scim_name" }, "active": { "type": "boolean", "description": "Whether the identity is active" }, "userType": { "type": "string", "enum": [ "TENANT_OWNER", "USER" ], "description": "\"TENANT_OWNER\" (also known as admin: true in the Tines API User schema) or \"USER\"" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/scim_group_member" }, "description": "Groups this user belongs to. Read-only; change membership by updating each Group's members" }, "meta": { "$ref": "#/components/schemas/scim_meta" } }, "description": "A SCIM 2.0 User resource" }, "scim_group": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "description": "SCIM schema URIs the resource conforms to" }, "id": { "type": "string", "description": "Identifier generated by Tines" }, "externalId": { "type": "string", "nullable": true, "description": "Identifier generated by the IdP" }, "displayName": { "type": "string", "description": "The display name for the group" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/scim_group_member" }, "description": "Users and Groups that belong to this Group" }, "meta": { "$ref": "#/components/schemas/scim_meta" } }, "description": "A SCIM 2.0 Group resource" }, "scim_name": { "type": "object", "properties": { "givenName": { "type": "string", "description": "The first name of the user" }, "familyName": { "type": "string", "description": "The last name of the user" } }, "description": "A SCIM name sub-attribute" }, "scim_group_member": { "type": "object", "properties": { "value": { "type": "string", "description": "Identifier of the member User or Group" }, "type": { "type": "string", "nullable": true, "description": "The member type (\"User\" or \"Group\")" }, "display": { "type": "string", "nullable": true, "description": "Human-readable name of the member" } }, "description": "A member reference within a SCIM Group" }, "scim_meta": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "The resource type (\"User\" or \"Group\")" }, "created": { "type": "string", "description": "ISO 8601 timestamp of when the resource was created" }, "lastModified": { "type": "string", "description": "ISO 8601 timestamp of when the resource was last modified" }, "location": { "type": "string", "description": "URI of the resource" } }, "description": "SCIM resource metadata" }, "scim_list_response": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "description": "SCIM schema URIs (urn:ietf:params:scim:api:messages:2.0:ListResponse)" }, "totalResults": { "type": "integer", "description": "Total number of resources matching the query" }, "startIndex": { "type": "integer", "description": "1-based index of the first result in this page" }, "itemsPerPage": { "type": "integer", "description": "Number of resources returned in this page" }, "Resources": { "type": "array", "items": { "type": "object" }, "description": "The page of matching resources (scim_user or scim_group objects)" } }, "description": "A SCIM 2.0 ListResponse envelope" }, "event": { "type": "object", "properties": { "id": { "type": "integer", "description": "Event ID" }, "agent_id": { "type": "integer", "description": "ID of the action that emitted the event" }, "payload": { "type": "object", "description": "JSON representation of the event payload" }, "created_at": { "type": "string", "description": "When the event was emitted" }, "updated_at": { "type": "string", "description": "When the event was last updated (always the same as created_at)" }, "story_run_guid": { "type": "string", "description": "Unique identifier of the event's story run" }, "previous_events_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of the upstream action's events in the event's story run" }, "re_emitted": { "type": "boolean", "description": "Whether this event has been re-emitted" } }, "description": "An event" }, "admin_user": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "scim_uid": { "type": "string", "nullable": true, "description": "SCIM user ID" }, "email": { "type": "string", "description": "User email" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "admin": { "type": "boolean", "description": "Whether the user is an admin" }, "is_active": { "type": "boolean", "description": "Whether the user is active" }, "tenant_permissions": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Tenant permission names granted to the user" }, "last_seen": { "type": "string", "nullable": true, "description": "When the user was last seen in the platform" }, "created_at": { "type": "string", "description": "When the user was created" }, "updated_at": { "type": "string", "description": "When the user was last updated" }, "team_memberships": { "type": "array", "items": { "$ref": "#/components/schemas/admin_user_team_membership" } } }, "description": "A user in the Tines tenant" }, "admin_user_team_membership": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "Team ID" }, "team_name": { "type": "string", "description": "Team name" }, "role": { "type": "string", "description": "The user's role in the team" } }, "description": "A user's membership of a shared team" }, "admin_role": { "type": "object", "properties": { "id": { "type": "string", "description": "Role ID" }, "name": { "type": "string", "description": "Role name" }, "type": { "type": "string", "description": "Role type, either `custom` or `default`" }, "description": { "type": "string", "nullable": true, "description": "Role description" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Permission names applied to the role" }, "created_at": { "type": "string", "nullable": true, "description": "When the role was created. Null for default roles" }, "updated_at": { "type": "string", "nullable": true, "description": "When the role was last updated. Null for default roles" }, "builder": { "type": "boolean", "description": "Whether the role grants builder / story editing permissions" } }, "description": "A default or custom role in the Tines tenant" }, "ip_access_control_rule": { "type": "object", "properties": { "id": { "type": "integer", "description": "Rule ID" }, "ip": { "type": "string", "description": "IP address or CIDR range of the rule" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the rule" }, "created_at": { "type": "string", "description": "When the rule was created" }, "updated_at": { "type": "string", "description": "When the rule was last updated" } }, "description": "A rule controlling which IP addresses may access the tenant" }, "login_activity": { "type": "object", "properties": { "id": { "type": "integer", "description": "Sign-in activity ID" }, "user_id": { "type": "integer", "description": "ID of the user that signed in" }, "ip": { "type": "string", "description": "IP address the sign-in came from" }, "user_agent": { "type": "string", "description": "User agent string of the client used to sign in" }, "created_at": { "type": "string", "description": "When the user signed in" } }, "description": "A user sign-in event" }, "user_group_mapping": { "type": "object", "properties": { "mappings": { "type": "array", "items": { "$ref": "#/components/schemas/user_group_mapping_entry" } }, "tenant_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/user_group_mapping_tenant_permission" } }, "tenant_owners_groups": { "type": "array", "items": { "type": "string" }, "description": "Groups whose members become tenant owners" } }, "description": "Mapping of identity-provider groups to Tines teams, roles, and tenant permissions" }, "user_group_mapping_tenant_permission": { "type": "object", "properties": { "group_name": { "type": "string", "description": "Name of the identity-provider group" }, "permission": { "type": "string", "description": "Name of the tenant permission granted to the group" } }, "description": "A single group-to-tenant-permission mapping" }, "user_group_mapping_entry": { "type": "object", "properties": { "group_name": { "type": "string", "description": "Name of the identity-provider group" }, "team_name": { "type": "string", "description": "Name of the Tines team" }, "role_name": { "type": "string", "description": "Name of the role granted in the team" } }, "description": "A single group-to-team-and-role mapping" }, "team_flow_usage": { "type": "object", "properties": { "id": { "type": "integer", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "flows_used": { "type": "integer", "description": "Number of flows currently used by stories in this team" }, "flows_allocated": { "type": "integer", "nullable": true, "description": "Number of flows allocated to this team. Null when the team has no allocation and draws from the tenant's unallocated flows" }, "flows_available": { "type": "integer", "nullable": true, "description": "Allocated flows not yet used by this team. Null when the team has no allocation" } }, "description": "Flow usage and allocation for a single team" }, "Error": { "type": "array", "items": { "type": "string" }, "description": "One or more messages describing why the request failed." }, "ForbiddenError": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/IpAccessControlError" } ], "description": "Domain enforcement returns the standard message array; IP access control returns its own object." }, "IpAccessControlError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } } }, "required": [ "errors" ], "additionalProperties": false, "description": "Returned when the tenant's IP access control rules block the request." }, "ErrorObject": { "type": "object", "properties": { "error": { "type": "string", "description": "A description of the error." } }, "required": [ "error" ], "additionalProperties": false, "description": "An error response containing a single message." }, "LicenseForbiddenError": { "oneOf": [ { "$ref": "#/components/schemas/ForbiddenError" }, { "$ref": "#/components/schemas/ErrorObject" } ], "description": "Tenant access controls use the standard forbidden shapes; the cloud-only license restriction returns a single error message." }, "ConditionalMismatchError": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string", "description": "A description of the error." }, "current_value": { "description": "The value the resource currently holds." } } } ], "description": "An if_value mismatch returns the object form, carrying the current value; every other validation failure returns the standard message array." }, "EmptyObjectError": { "type": "object", "properties": {}, "additionalProperties": false, "description": "An error response with an empty body object." }, "RecordsQueryError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "description": "A machine-readable error type, such as bad_request or query_timeout." }, "message": { "type": "string", "description": "A description of the error." }, "field": { "type": "string", "description": "The request field the error relates to, when known." }, "hint": { "type": "string", "description": "How to resolve the error, when a suggestion applies." } } } }, "description": "The error shape used by the records query endpoint." }, "RunScriptEnvironmentError": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always false on an error response." }, "error": { "type": "string", "description": "A short summary of the error, such as Bad request." }, "message": { "type": "string", "description": "A description of the error." }, "code": { "type": "string", "description": "A stable machine-readable error code, when available." }, "details": { "type": "array", "items": { "type": "string" }, "description": "Individual validation messages, on a validation failure." }, "error_id": { "type": "string", "description": "An identifier to quote when contacting support." } }, "required": [ "success", "error", "message" ], "additionalProperties": false, "description": "The error shape used by the run script environment endpoints." }, "RunScriptEnvironmentForbiddenError": { "oneOf": [ { "$ref": "#/components/schemas/ForbiddenError" }, { "$ref": "#/components/schemas/RunScriptEnvironmentError" } ], "description": "Tenant access controls use the standard forbidden shapes; endpoint authorization uses the run script environment envelope." }, "RunScriptEnvironmentUnauthorizedError": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RunScriptEnvironmentError" } ], "description": "A missing or invalid API key uses the run script environment envelope; a tenant without stories uses the standard message array." } }, "responses": { "BadRequest": { "description": "The request was malformed, or a parameter failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "EventPageTooLarge": { "description": "The event payloads on the requested page are too large to return together. Lower per_page, or filter the results more narrowly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "LicenseForbidden": { "description": "The endpoint is only available on self-hosted installations; the request can also be blocked by the tenant's IP access control rules or domain enforcement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseForbiddenError" } } } }, "InvalidLicense": { "description": "The license string is not a valid signed Tines license.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorObject" } } } }, "ConditionalMismatch": { "description": "The resource is locked, the key or index does not exist, or if_value did not match the current value — in which case the response carries that value so the caller can retry against it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalMismatchError" } } } }, "RunScriptEnvironmentUnauthorized": { "description": "The API key is missing, invalid, or belongs to a deactivated user; or the tenant does not have access to stories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunScriptEnvironmentUnauthorizedError" } } } }, "InvalidTagColor": { "description": "color is neither one of the named colors nor a #RRGGBB hex value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }