{ "openapi": "3.0.3", "info": { "title": "Tines Cases 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/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/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/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/case_files/{guid}": { "get": { "summary": "Download a case file", "operationId": "get_api_v1_case_files_by_guid", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1) > Files" ], "deprecated": true, "parameters": [ { "name": "guid", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The file GUID" } ], "responses": { "200": { "description": "Binary file content" } } } }, "/api/v1/case_inputs": { "get": { "summary": "List fields", "operationId": "get_api_v1_case_inputs", "tags": [ "Cases (v1) > Fields" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Only include fields from a specific 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": { "case_inputs": { "type": "array", "items": { "$ref": "#/components/schemas/case_input" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a field", "operationId": "post_api_v1_case_inputs", "tags": [ "Cases (v1) > Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The field name" }, "input_type": { "type": "string", "enum": [ "string", "number", "boolean", "timestamp" ], "description": "The field type" }, "team_id": { "type": "integer", "description": "The team to add the field to" }, "sensitive": { "type": "boolean", "description": "Whether the sensitive field permission is required to read or write this field" }, "validation_type": { "type": "string", "enum": [ "options", "regex" ], "description": "Validation type for the field" }, "validation_options": { "type": "object", "description": "Validation options (array of values for options, regex pattern for regex)" }, "group_name": { "type": "string", "description": "The name of the group to assign the field to" } }, "required": [ "name", "input_type", "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_input" } } } } } } }, "/api/v1/case_inputs/{case_input_id}/fields": { "get": { "summary": "List field values", "operationId": "get_api_v1_case_inputs_by_case_input_id_fields", "tags": [ "Cases (v1) > Fields" ], "parameters": [ { "name": "case_input_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field ID to list values for" }, { "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": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/case_input_field_value" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/case_inputs/{id}": { "get": { "summary": "Get a field", "operationId": "get_api_v1_case_inputs_by_id", "tags": [ "Cases (v1) > Fields" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_input" } } } } } } }, "/api/v1/case_sub_statuses": { "get": { "summary": "List case statuses", "operationId": "get_api_v1_case_sub_statuses", "tags": [ "Cases (v1) > Case Statuses" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "The team whose case statuses to retrieve" }, { "name": "parent_status", "in": "query", "schema": { "type": "string", "enum": [ "OPEN", "CLOSED" ] }, "description": "Filter by parent status" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter statuses 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": { "case_sub_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/case_sub_status" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a case status", "operationId": "post_api_v1_case_sub_statuses", "tags": [ "Cases (v1) > Case Statuses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team to create the status for" }, "name": { "type": "string", "description": "Case status name" }, "parent_status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "Parent status (defaults to OPEN)" }, "description": { "type": "string", "description": "A description for the status" } }, "required": [ "team_id", "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_sub_status" } } } } } } }, "/api/v1/case_sub_statuses/{id}": { "delete": { "summary": "Delete a case status", "operationId": "delete_api_v1_case_sub_statuses_by_id", "tags": [ "Cases (v1) > Case Statuses" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case status ID" }, { "name": "fallback_status_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "The case status ID that cases using the deleted status are reassigned to" } ], "responses": { "204": { "description": "Empty response on success" }, "400": { "description": "fallback_status_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Get a case status", "operationId": "get_api_v1_case_sub_statuses_by_id", "tags": [ "Cases (v1) > Case Statuses" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case status ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_sub_status" } } } } } }, "patch": { "summary": "Update a case status", "operationId": "patch_api_v1_case_sub_statuses_by_id", "tags": [ "Cases (v1) > Case Statuses" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case status ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated status name" }, "description": { "type": "string", "description": "Updated description" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_sub_status" } } } } } }, "put": { "summary": "Update a case status", "operationId": "put_api_v1_case_sub_statuses_by_id", "tags": [ "Cases (v1) > Case Statuses" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case status ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated status name" }, "description": { "type": "string", "description": "Updated description" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_sub_status" } } } } } } }, "/api/v1/case_templates": { "get": { "summary": "List case templates", "operationId": "get_api_v1_case_templates", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "required": true, "description": "Return case templates belonging to this team" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search against case template name" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (max 100)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_templates": { "type": "array", "items": { "$ref": "#/components/schemas/case_template" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a case template", "operationId": "post_api_v1_case_templates", "description": "Create a case template in a team. Template names must be unique within the team.", "tags": [ "Cases (v1) > Case Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team to create the template in" }, "name": { "type": "string", "description": "Template name" }, "emoji": { "type": "string", "description": "Template emoji, as a shortcode such as :mag:. A random emoji is assigned when omitted" }, "options": { "type": "object", "properties": { "name": { "type": "string", "description": "The name given to cases created from this template. Supports formulas and field mentions" }, "description": { "type": "string", "description": "The description given to cases created from this template. Supports markdown, formulas and field mentions" }, "status": { "type": "string", "enum": [ "open", "closed" ], "description": "The status given to cases created from this template" }, "priority": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ], "description": "The priority given to cases created from this template" }, "sub_status_id": { "type": "integer", "description": "The ID of the case sub-status given to cases created from this template" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Array of user email addresses to assign. Emails that do not match a user on the team are dropped" }, "tag_names": { "type": "array", "items": { "type": "string" }, "description": "Array of tag name strings. Tags are found or created on the team, and resolved to IDs" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Array of case action objects, each with `button_type` (one of `webhook`, `page`, `chat`, `story`, or `app`), `url`, `label` (tooltip), and `button_text`" }, "tasks": { "type": "array", "items": { "type": "object" }, "description": "Array of task objects, each with `description` and an optional `assignee_emails` array" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of case requirement objects, each with `name` and `formula`. All formulas must evaluate to true before a case can be closed" }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "Array of block objects, each with `guid`, `title`, `block_type`, `hidden`, `parent_block_guid`, and an `elements` array of `{content, note_type, color, sensitive}` objects" }, "field_values": { "type": "object", "description": "Object mapping field ID to the value that field is pre-filled with. Replaces all existing field values" }, "metadata": { "type": "object", "description": "Case metadata represented as key-value pairs" } }, "description": "Template configuration options. Keys you omit keep their existing values; keys you provide replace theirs wholesale. Formulas are stored as written and evaluated when a case is created from the template, against the event that triggered the case creation." } }, "required": [ "team_id", "name" ] }, "example": { "team_id": 2, "name": "Phishing investigation", "emoji": ":fishing_pole_and_fish:", "options": { "name": "Phishing report for <>", "description": "Investigate the reported email", "priority": "high", "tag_names": [ "phishing", "email" ], "assignee_emails": [ "analyst@example.com" ], "tasks": [ { "description": "Review headers and attachments", "assignee_emails": [ "analyst@example.com" ] } ], "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ], "metadata": { "source": "user_report" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_template" }, "example": { "id": 12, "name": "Phishing investigation", "emoji": ":fishing_pole_and_fish:", "team": { "id": 2, "name": "Security" }, "created_at": "2026-05-25T10:00:00Z", "updated_at": "2026-05-25T10:00:00Z" } } } }, "400": { "description": "team_id is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/case_templates/{id}": { "delete": { "summary": "Delete a case template", "operationId": "delete_api_v1_case_templates_by_id", "description": "Delete a case template. Cases already created from the template are not affected.", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case template ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a case template", "operationId": "get_api_v1_case_templates_by_id", "description": "Retrieve a single case template. To see the shape a case created from this template would take, use the preview endpoint.", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case template ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_template" }, "example": { "id": 12, "name": "Phishing investigation", "emoji": ":fishing_pole_and_fish:", "team": { "id": 2, "name": "Security" }, "created_at": "2026-05-25T10:00:00Z", "updated_at": "2026-05-25T10:00:00Z" } } } } } }, "patch": { "summary": "Update a case template", "operationId": "patch_api_v1_case_templates_by_id", "description": "Update a case template. Updates are partial: options you do not send keep their existing values.", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated template name" }, "emoji": { "type": "string", "description": "Updated template emoji, as a shortcode such as :mag:" }, "options": { "type": "object", "properties": { "name": { "type": "string", "description": "The name given to cases created from this template. Supports formulas and field mentions" }, "description": { "type": "string", "description": "The description given to cases created from this template. Supports markdown, formulas and field mentions" }, "status": { "type": "string", "enum": [ "open", "closed" ], "description": "The status given to cases created from this template" }, "priority": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ], "description": "The priority given to cases created from this template" }, "sub_status_id": { "type": "integer", "description": "The ID of the case sub-status given to cases created from this template" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Array of user email addresses to assign. Emails that do not match a user on the team are dropped" }, "tag_names": { "type": "array", "items": { "type": "string" }, "description": "Array of tag name strings. Tags are found or created on the team, and resolved to IDs" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Array of case action objects, each with `button_type` (one of `webhook`, `page`, `chat`, `story`, or `app`), `url`, `label` (tooltip), and `button_text`" }, "tasks": { "type": "array", "items": { "type": "object" }, "description": "Array of task objects, each with `description` and an optional `assignee_emails` array" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of case requirement objects, each with `name` and `formula`. All formulas must evaluate to true before a case can be closed" }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "Array of block objects, each with `guid`, `title`, `block_type`, `hidden`, `parent_block_guid`, and an `elements` array of `{content, note_type, color, sensitive}` objects" }, "field_values": { "type": "object", "description": "Object mapping field ID to the value that field is pre-filled with. Replaces all existing field values" }, "metadata": { "type": "object", "description": "Case metadata represented as key-value pairs" } }, "description": "Template configuration options. Keys you omit keep their existing values; keys you provide replace theirs wholesale. Formulas are stored as written and evaluated when a case is created from the template, against the event that triggered the case creation." } } }, "example": { "name": "Phishing investigation", "options": { "priority": "critical", "tag_names": [ "phishing", "escalated" ] } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_template" }, "example": { "id": 12, "name": "Phishing investigation", "emoji": ":fishing_pole_and_fish:", "team": { "id": 2, "name": "Security" }, "created_at": "2026-05-25T10:00:00Z", "updated_at": "2026-05-26T09:30:00Z" } } } } } }, "put": { "summary": "Update a case template", "operationId": "put_api_v1_case_templates_by_id", "description": "Update a case template. Updates are partial: options you do not send keep their existing values.", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case template ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated template name" }, "emoji": { "type": "string", "description": "Updated template emoji, as a shortcode such as :mag:" }, "options": { "type": "object", "properties": { "name": { "type": "string", "description": "The name given to cases created from this template. Supports formulas and field mentions" }, "description": { "type": "string", "description": "The description given to cases created from this template. Supports markdown, formulas and field mentions" }, "status": { "type": "string", "enum": [ "open", "closed" ], "description": "The status given to cases created from this template" }, "priority": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ], "description": "The priority given to cases created from this template" }, "sub_status_id": { "type": "integer", "description": "The ID of the case sub-status given to cases created from this template" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Array of user email addresses to assign. Emails that do not match a user on the team are dropped" }, "tag_names": { "type": "array", "items": { "type": "string" }, "description": "Array of tag name strings. Tags are found or created on the team, and resolved to IDs" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Array of case action objects, each with `button_type` (one of `webhook`, `page`, `chat`, `story`, or `app`), `url`, `label` (tooltip), and `button_text`" }, "tasks": { "type": "array", "items": { "type": "object" }, "description": "Array of task objects, each with `description` and an optional `assignee_emails` array" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of case requirement objects, each with `name` and `formula`. All formulas must evaluate to true before a case can be closed" }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "Array of block objects, each with `guid`, `title`, `block_type`, `hidden`, `parent_block_guid`, and an `elements` array of `{content, note_type, color, sensitive}` objects" }, "field_values": { "type": "object", "description": "Object mapping field ID to the value that field is pre-filled with. Replaces all existing field values" }, "metadata": { "type": "object", "description": "Case metadata represented as key-value pairs" } }, "description": "Template configuration options. Keys you omit keep their existing values; keys you provide replace theirs wholesale. Formulas are stored as written and evaluated when a case is created from the template, against the event that triggered the case creation." } } }, "example": { "name": "Phishing investigation", "options": { "priority": "critical", "tag_names": [ "phishing", "escalated" ] } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_template" }, "example": { "id": 12, "name": "Phishing investigation", "emoji": ":fishing_pole_and_fish:", "team": { "id": 2, "name": "Security" }, "created_at": "2026-05-25T10:00:00Z", "updated_at": "2026-05-26T09:30:00Z" } } } } } } }, "/api/v1/case_templates/{id}/export": { "get": { "summary": "Export a case template", "operationId": "get_api_v1_case_templates_by_id_export", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case template ID" } ], "responses": { "200": { "description": "Exported template JSON" } } } }, "/api/v1/case_templates/{id}/preview": { "get": { "summary": "Preview a case template", "operationId": "get_api_v1_case_templates_by_id_preview", "description": "Resolve a case template into the shape a case created from it would take, with tag, sub-status, assignee, and field references expanded into full objects. Formulas and field mentions are returned unevaluated, since there is no case to evaluate them against yet.", "tags": [ "Cases (v1) > Case Templates" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case template ID" } ], "responses": { "200": { "description": "Template preview data, or null when preview data cannot be generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The case name" }, "description": { "type": "string", "nullable": true, "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status. Defaults to `OPEN` when the template does not set one" }, "priority": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO" ], "nullable": true, "description": "The case priority" }, "sub_status": { "type": "object", "properties": { "id": { "type": "integer", "description": "The case sub-status ID" }, "name": { "type": "string", "description": "The case sub-status name" } }, "nullable": true, "description": "The case sub-status, with its ID and name" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The assignee's user ID" }, "email": { "type": "string", "description": "The assignee's email address" }, "first_name": { "type": "string", "description": "The assignee's first name" }, "last_name": { "type": "string", "description": "The assignee's last name" }, "avatar_url": { "type": "string", "nullable": true, "description": "The assignee's avatar URL" } }, "description": "An assignee" }, "description": "The users the case is assigned to" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The tag ID" }, "name": { "type": "string", "description": "The tag name" } }, "description": "A tag" }, "description": "The tags applied to the case" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "nullable": true, "description": "The value the field is pre-filled with" }, "case_input": { "type": "object", "properties": { "id": { "type": "integer", "description": "The field ID" }, "key": { "type": "string", "description": "The lookup key of the field" }, "name": { "type": "string", "description": "The field name" }, "validation_type": { "type": "string", "enum": [ "none", "options", "regex" ], "description": "The validation type of the field" }, "validation_options": { "type": "object", "nullable": true, "description": "The validation configuration of the field" } }, "description": "The field definition" } }, "description": "A field value" }, "description": "The case fields and the values they are pre-filled with" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action_type": { "type": "string", "enum": [ "webhook", "page", "chat", "story", "app" ], "description": "The action type" }, "action_text": { "type": "string", "nullable": true, "description": "The text shown on the action" }, "url": { "type": "string", "nullable": true, "description": "The URL the action calls" }, "label": { "type": "string", "nullable": true, "description": "The action tooltip" } }, "description": "A case action" }, "description": "The case actions available on the case" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The block GUID" }, "title": { "type": "string", "nullable": true, "description": "The block title" }, "block_type": { "type": "string", "nullable": true, "description": "The block type" }, "position": { "type": "integer", "description": "The 1-based position of the block on the case" }, "hidden": { "type": "boolean", "nullable": true, "description": "Whether the block is hidden" }, "block_group_id": { "type": "string", "nullable": true, "description": "The GUID of the block group this block sits in" }, "elements": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "nullable": true, "description": "The element content" }, "note_type": { "type": "string", "enum": [ "text", "html" ], "nullable": true, "description": "The note format" }, "color": { "type": "string", "nullable": true, "description": "The note color" }, "sensitive": { "type": "boolean", "nullable": true, "description": "Whether the element holds sensitive content" } }, "description": "A block element" }, "description": "The elements the block contains" } }, "description": "A block" }, "description": "The blocks laid out on the case" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "The task description" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The assignee's user ID" }, "email": { "type": "string", "description": "The assignee's email address" }, "first_name": { "type": "string", "description": "The assignee's first name" }, "last_name": { "type": "string", "description": "The assignee's last name" } }, "description": "A task assignee" }, "description": "The users the task is assigned to" } }, "description": "A task" }, "description": "The tasks added to the case" }, "closure_conditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The case requirement name" }, "formula": { "type": "string", "description": "The formula that must evaluate to true" } }, "description": "A case requirement" }, "description": "The case requirements that must evaluate to true before the case can be closed" }, "metadata": { "type": "object", "description": "Case metadata represented as key-value pairs" } } }, "example": { "name": "Phishing report for <>", "description": "Investigate the reported email", "status": "OPEN", "priority": "MEDIUM", "sub_status": { "id": 88, "name": "Triage" }, "assignees": [ { "user_id": "2435", "email": "analyst@example.com", "first_name": "Ada", "last_name": "Lovelace", "avatar_url": null } ], "tags": [ { "id": 17, "name": "phishing" } ], "fields": [ { "value": "user@example.com", "case_input": { "id": 91, "key": "reporter_email", "name": "Reporter email", "validation_type": "none", "validation_options": null } } ], "actions": [ { "action_type": "page", "action_text": "Open form", "url": "https://tenant.tines.com/pages/55e94b9b4e26175051c0287f4259363f/", "label": "Isolate host and give reason" } ], "blocks": [ { "id": "block-1", "title": "Investigation notes", "block_type": "note", "position": 1, "hidden": false, "block_group_id": null, "elements": [ { "content": "Initial triage required.", "note_type": "text", "color": "gold", "sensitive": null } ] } ], "tasks": [ { "description": "Review headers and attachments", "assignees": [ { "id": "2435", "email": "analyst@example.com", "first_name": "Ada", "last_name": "Lovelace" } ] } ], "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ], "metadata": { "source": "user_report" } } } } } } } }, "/api/v1/case_templates/import": { "post": { "summary": "Import a case template", "operationId": "post_api_v1_case_templates_import", "tags": [ "Cases (v1) > Case Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team to import the template into" }, "data": { "type": "object", "description": "Exported template JSON payload" } }, "required": [ "team_id", "data" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_templates": { "type": "array", "items": { "$ref": "#/components/schemas/case_template" } } } } } } } } } }, "/api/v1/case_webhooks": { "get": { "summary": "List case webhooks", "operationId": "get_api_v1_case_webhooks", "tags": [ "Cases (v1) > Webhooks" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Restrict results to a single team" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page (max 50)" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/case_webhook" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a case webhook", "operationId": "post_api_v1_case_webhooks", "tags": [ "Cases (v1) > Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team_id": { "type": "integer", "description": "The team to create the webhook for" }, "url": { "type": "string", "description": "The destination URL the webhook posts to" }, "name": { "type": "string", "description": "A display name for the webhook" }, "notifications": { "type": "array", "items": { "type": "string" }, "description": "Event types that trigger the webhook (defaults to ALL)" } }, "required": [ "team_id", "url" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_webhook" } } } } } } }, "/api/v1/case_webhooks/{id}": { "delete": { "summary": "Delete a case webhook", "operationId": "delete_api_v1_case_webhooks_by_id", "tags": [ "Cases (v1) > Webhooks" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The webhook ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a case webhook", "operationId": "get_api_v1_case_webhooks_by_id", "tags": [ "Cases (v1) > Webhooks" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The webhook ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_webhook" } } } } } }, "patch": { "summary": "Update a case webhook", "operationId": "patch_api_v1_case_webhooks_by_id", "tags": [ "Cases (v1) > Webhooks" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The webhook ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "A new destination URL" }, "name": { "type": "string", "description": "A new display name" }, "notifications": { "type": "array", "items": { "type": "string" }, "description": "Event types that trigger the webhook" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_webhook" } } } } } }, "put": { "summary": "Update a case webhook", "operationId": "put_api_v1_case_webhooks_by_id", "tags": [ "Cases (v1) > Webhooks" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The webhook ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "A new destination URL" }, "name": { "type": "string", "description": "A new display name" }, "notifications": { "type": "array", "items": { "type": "string" }, "description": "Event types that trigger the webhook" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_webhook" } } } } } } }, "/api/v1/cases": { "get": { "summary": "List cases", "operationId": "get_api_v1_cases", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "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" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by team ID" }, { "name": "filters", "in": "query", "schema": { "type": "object", "properties": { "search": { "type": "string", "description": "Free-text search across case content" }, "name": { "type": "string", "description": "Filter by case name" }, "comment": { "type": "string", "description": "Filter by comment content" }, "note": { "type": "string", "description": "Filter by note content" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED" ] }, "description": "Filter by status" }, "sub_status_names": { "type": "array", "items": { "type": "string" }, "description": "Filter by sub-status names" }, "priority": { "type": "array", "items": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL", "INFO" ] }, "description": "Filter by priority" }, "severity": { "type": "string", "description": "Filter by severity (alias for priority)" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tag names (AND logic, alias for and_tags)" }, "or_tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tag names (OR logic)" }, "and_tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tag names (AND logic)" }, "exclude_tags": { "type": "array", "items": { "type": "string" }, "description": "Exclude tag names" }, "assignees": { "type": "array", "items": { "type": "integer" }, "description": "Filter by assignee user IDs" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Filter by assignee email addresses" }, "unassigned": { "type": "boolean", "description": "Filter for unassigned cases" }, "assigned_to_me": { "type": "boolean", "description": "Filter for cases assigned to current user" }, "subscribed": { "type": "boolean", "description": "Filter for cases user is subscribed to" }, "my_open_tasks": { "type": "boolean", "description": "Filter for cases with open tasks assigned to current user" }, "authors": { "type": "array", "items": { "type": "integer" }, "description": "Filter by author user IDs" }, "exclude_authors": { "type": "array", "items": { "type": "integer" }, "description": "Exclude author user IDs" }, "author_emails": { "type": "array", "items": { "type": "string" }, "description": "Filter by author email addresses" }, "metadata": { "type": "object", "description": "Filter by metadata key-value pairs" }, "or_metadata": { "type": "object", "description": "Filter by metadata (OR logic)" }, "fields": { "type": "object", "description": "Filter by field values" }, "or_fields": { "type": "object", "description": "Filter by field values (OR logic)" }, "sla": { "type": "array", "items": { "type": "string" }, "description": "Filter by SLA status (legacy alias for sla_status)" }, "sla_status": { "type": "array", "items": { "type": "string", "enum": [ "WARNING", "EXCEEDED" ] }, "description": "Filter by SLA status" }, "sla_type": { "type": "array", "items": { "type": "string" }, "description": "Filter by SLA type" }, "start_date": { "type": "string", "description": "Filter by created_at start date (ISO 8601)" }, "end_date": { "type": "string", "description": "Filter by created_at end date (ISO 8601)" }, "relative_date": { "type": "string", "description": "Filter by relative date (e.g. 'last_7_days')" }, "time_range": { "type": "string", "description": "Filter by time range" }, "resolved_at_start_date": { "type": "string", "description": "Filter by resolved_at start date (ISO 8601)" }, "resolved_at_end_date": { "type": "string", "description": "Filter by resolved_at end date (ISO 8601)" }, "resolved_at_relative_date": { "type": "string", "description": "Filter by resolved_at relative date" }, "updated_at_start_date": { "type": "string", "description": "Filter by updated_at start date (ISO 8601)" }, "updated_at_end_date": { "type": "string", "description": "Filter by updated_at end date (ISO 8601)" }, "updated_at_relative_date": { "type": "string", "description": "Filter by updated_at relative date" }, "records": { "type": "array", "items": { "type": "string" }, "description": "Filter by record type names" }, "record_field": { "type": "object", "description": "Filter by record field values" }, "case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by specific case IDs" }, "child_team_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by child team IDs" } } }, "description": "Filter criteria" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/case_v1" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "408": { "$ref": "#/components/responses/CaseSearchTimeout" } } }, "post": { "summary": "Create a case", "operationId": "post_api_v1_cases", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The case name" }, "team_id": { "type": "integer", "description": "Team to create the case in (defaults to the user's default team)" }, "description": { "type": "string", "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status" }, "priority": { "type": "string", "description": "The case priority (maps to severity)" }, "severity": { "type": "string", "description": "The case severity (alias for priority)" }, "sub_status_id": { "type": "integer", "description": "The sub-status ID" }, "author_email": { "type": "string", "description": "Email address of the case author" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees" }, "tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to apply" }, "record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to attach" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Array of {button_type, url, label, button_text} objects" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of {name, formula} objects" }, "metadata": { "type": "object", "description": "Metadata key-value pairs" }, "opened_at": { "type": "string", "description": "When the case was opened (ISO 8601)" }, "resolved_at": { "type": "string", "description": "When the case was resolved (ISO 8601)" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_v1" } } } }, "400": { "description": "team_id is missing, tag_names is not an array, or an assignee email is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cases/{case_case_id}/assignees": { "get": { "summary": "List assignees", "operationId": "get_api_v1_cases_by_case_case_id_assignees", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/assignees).**", "tags": [ "Cases (v1) > Assignees" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/user" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "case_id": { "type": "integer", "description": "The case ID" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/cases/{case_case_id}/buttons": { "get": { "summary": "List actions", "operationId": "get_api_v1_cases_by_case_case_id_buttons", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/actions).**", "tags": [ "Cases (v1) > Actions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Actions (id, url, label, story_name, page_emoji, story_emoji, button_type, button_text, created_at, updated_at)" } } } } } } } }, "post": { "summary": "Create an action", "operationId": "post_api_v1_cases_by_case_case_id_buttons", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/actions).**", "tags": [ "Cases (v1) > Actions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "button_type": { "type": "string", "description": "Action type (e.g. webhook, page)" }, "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "button_text": { "type": "string", "description": "Action text" } }, "required": [ "button_type", "url", "label" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_v1" } } } } } } }, "/api/v1/cases/{case_case_id}/buttons/{id}": { "delete": { "summary": "Delete an action", "operationId": "delete_api_v1_cases_by_case_case_id_buttons_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/actions).**", "tags": [ "Cases (v1) > Actions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an action", "operationId": "get_api_v1_cases_by_case_case_id_buttons_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/actions).**", "tags": [ "Cases (v1) > Actions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_v1" } } } } } }, "patch": { "summary": "Update an action", "operationId": "patch_api_v1_cases_by_case_case_id_buttons_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/actions).**", "tags": [ "Cases (v1) > Actions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "button_type": { "type": "string", "description": "Action type (e.g. webhook, page)" }, "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "button_text": { "type": "string", "description": "Action text" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_v1" } } } } } }, "put": { "summary": "Update an action", "operationId": "put_api_v1_cases_by_case_case_id_buttons_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/actions).**", "tags": [ "Cases (v1) > Actions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "button_type": { "type": "string", "description": "Action type (e.g. webhook, page)" }, "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "button_text": { "type": "string", "description": "Action text" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action_v1" } } } } } } }, "/api/v1/cases/{case_case_id}/comments": { "post": { "summary": "Create a comment", "operationId": "post_api_v1_cases_by_case_case_id_comments", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The comment text" }, "author_email": { "type": "string", "description": "Email address of the comment author" } }, "required": [ "value" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity_v1" } } } } } } }, "/api/v1/cases/{case_case_id}/comments/{id}": { "delete": { "summary": "Delete a comment", "operationId": "delete_api_v1_cases_by_case_case_id_comments_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "patch": { "summary": "Update a comment", "operationId": "patch_api_v1_cases_by_case_case_id_comments_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The comment text" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity_v1" } } } } } }, "put": { "summary": "Update a comment", "operationId": "put_api_v1_cases_by_case_case_id_comments_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The comment text" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity_v1" } } } } } } }, "/api/v1/cases/{case_case_id}/comments/{id}/add_reaction": { "post": { "summary": "Add a reaction to a comment", "operationId": "post_api_v1_cases_by_case_case_id_comments_by_id_add_reaction", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments > Reactions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Emoji name without colons" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity_v1" } } } } } } }, "/api/v1/cases/{case_case_id}/comments/{id}/remove_reaction": { "post": { "summary": "Remove a reaction from a comment", "operationId": "post_api_v1_cases_by_case_case_id_comments_by_id_remove_reaction", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments > Reactions" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Emoji name without colons" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity_v1" } } } } } } }, "/api/v1/cases/{case_case_id}/files": { "post": { "summary": "Attach a file", "operationId": "post_api_v1_cases_by_case_case_id_files", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/files).**", "tags": [ "Cases (v1) > Files" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The file name" }, "file_contents": { "type": "string", "description": "Base64-encoded file contents" }, "value": { "type": "string", "description": "Comment text to accompany the file" }, "author_email": { "type": "string", "description": "Email address of the author" }, "team_case_block_id": { "type": "integer", "description": "ID of a file block to attach the file to" } }, "required": [ "filename", "file_contents" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "id": { "type": "integer", "description": "The file activity ID" }, "action": { "type": "string", "description": "Type of activity" }, "value": { "type": "string", "nullable": true, "description": "Comment text" }, "user": { "$ref": "#/components/schemas/user" }, "block_id": { "type": "string", "nullable": true, "description": "The file block ID (present when team_case_block_id was supplied)" } } } } } } } } }, "/api/v1/cases/{case_case_id}/files/{id}": { "delete": { "summary": "Delete a file", "operationId": "delete_api_v1_cases_by_case_case_id_files_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/files).**", "tags": [ "Cases (v1) > Files" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The file activity ID" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/cases/{case_case_id}/linked_cases": { "get": { "summary": "List linked cases", "operationId": "get_api_v1_cases_by_case_case_id_linked_cases", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/linked_cases).**", "tags": [ "Cases (v1) > Linked Cases" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "name": { "type": "string", "description": "The case name" }, "linked_cases": { "type": "array", "items": { "$ref": "#/components/schemas/linked_case" } } } } } } } } }, "post": { "summary": "Link a case", "operationId": "post_api_v1_cases_by_case_case_id_linked_cases", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/linked_cases).**", "tags": [ "Cases (v1) > Linked Cases" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID of the case to link" } }, "required": [ "id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "name": { "type": "string", "description": "The case name" }, "linked_cases": { "type": "array", "items": { "$ref": "#/components/schemas/linked_case" } } } } } } } } } }, "/api/v1/cases/{case_case_id}/linked_cases/{id}": { "delete": { "summary": "Unlink a case", "operationId": "delete_api_v1_cases_by_case_case_id_linked_cases_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/linked_cases).**", "tags": [ "Cases (v1) > Linked Cases" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the case to unlink" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/cases/{case_case_id}/metadata": { "delete": { "summary": "Delete metadata keys", "operationId": "delete_api_v1_cases_by_case_case_id_metadata", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/metadata).**", "tags": [ "Cases (v1) > Metadata" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "array", "items": { "type": "string" }, "description": "Metadata keys to delete" } }, "required": [ "metadata" ] } } } }, "responses": { "204": { "description": "Empty response on success" }, "400": { "description": "metadata is not an array of keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List metadata", "operationId": "get_api_v1_cases_by_case_case_id_metadata", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/metadata).**", "tags": [ "Cases (v1) > Metadata" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } } } }, "post": { "summary": "Add metadata", "operationId": "post_api_v1_cases_by_case_case_id_metadata", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/metadata).**", "tags": [ "Cases (v1) > Metadata" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "description": "Metadata key-value pairs to add (returns 409 if a key already exists)" } }, "required": [ "metadata" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } }, "400": { "description": "metadata is missing, empty, or is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "One of the keys in the request already has a value on the case. This endpoint only creates keys; use PUT to update an existing key. The check is per key, so a batch containing one existing key sets none of them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update metadata", "operationId": "put_api_v1_cases_by_case_case_id_metadata", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/metadata).**", "tags": [ "Cases (v1) > Metadata" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "description": "Metadata key-value pairs to update (keys must already exist)" } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } }, "400": { "description": "metadata is missing, empty, or is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cases/{case_case_id}/metadata/{id}": { "get": { "summary": "Get metadata by key", "operationId": "get_api_v1_cases_by_case_case_id_metadata_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/metadata).**", "tags": [ "Cases (v1) > Metadata" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The metadata key" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } } } } }, "/api/v1/cases/{case_case_id}/records": { "get": { "summary": "List records", "operationId": "get_api_v1_cases_by_case_case_id_records", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/records).**", "tags": [ "Cases (v1) > Records" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" }, { "name": "record_type_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by record type ID" }, { "name": "parent_record_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by parent record ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/record_v1" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "case_id": { "type": "integer", "description": "The case ID" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Attach a record to a case", "operationId": "post_api_v1_cases_by_case_case_id_records", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/records).**", "tags": [ "Cases (v1) > Records" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_id": { "type": "integer", "description": "The record ID" } }, "required": [ "record_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "record_id": { "type": "integer", "description": "The record ID" } } } } } } } } }, "/api/v1/cases/{case_case_id}/records/{id}": { "delete": { "summary": "Remove a record from a case", "operationId": "delete_api_v1_cases_by_case_case_id_records_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/records).**", "tags": [ "Cases (v1) > Records" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a record", "operationId": "get_api_v1_cases_by_case_case_id_records_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/records).**", "tags": [ "Cases (v1) > Records" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "record": { "$ref": "#/components/schemas/record_v1" } } } } } } } } }, "/api/v1/cases/{case_case_id}/subscribers": { "get": { "summary": "List subscribers", "operationId": "get_api_v1_cases_by_case_case_id_subscribers", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/subscribers).**", "tags": [ "Cases (v1) > Subscribers" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/user" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "case_id": { "type": "integer", "description": "The case ID" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Subscribe a user", "operationId": "post_api_v1_cases_by_case_case_id_subscribers", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/subscribers).**", "tags": [ "Cases (v1) > Subscribers" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_email": { "type": "string", "description": "Email address of the user to subscribe" } }, "required": [ "user_email" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "user": { "$ref": "#/components/schemas/user" } } } } } } } } }, "/api/v1/cases/{case_case_id}/subscribers/{id}": { "delete": { "summary": "Unsubscribe a user", "operationId": "delete_api_v1_cases_by_case_case_id_subscribers_by_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/subscribers).**", "tags": [ "Cases (v1) > Subscribers" ], "deprecated": true, "parameters": [ { "name": "case_case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Unused; the user is identified by user_email" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_email": { "type": "string", "description": "Email address of the user to unsubscribe" } }, "required": [ "user_email" ] } } } }, "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v1/cases/{case_id}": { "delete": { "summary": "Delete a case", "operationId": "delete_api_v1_cases_by_case_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a case", "operationId": "get_api_v1_cases_by_case_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_v1" } } } } } }, "patch": { "summary": "Update a case", "operationId": "patch_api_v1_cases_by_case_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The case name" }, "team_id": { "type": "integer", "description": "The team ID" }, "description": { "type": "string", "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status" }, "priority": { "type": "string", "description": "The case priority (maps to severity)" }, "severity": { "type": "string", "description": "The case severity (alias for priority)" }, "sub_status_id": { "type": "integer", "description": "The sub-status ID" }, "author_email": { "type": "string", "description": "Email address of the case author" }, "add_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to add" }, "remove_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to remove" }, "add_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to add" }, "remove_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to remove" }, "record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to set on the case" }, "add_record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to add" }, "remove_record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to remove" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Array of {button_type, url, label, button_text} objects" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of {name, formula} objects" }, "metadata": { "type": "object", "description": "Metadata key-value pairs" }, "opened_at": { "type": "string", "description": "When the case was opened (ISO 8601)" }, "resolved_at": { "type": "string", "description": "When the case was resolved (ISO 8601)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_v1" } } } }, "400": { "description": "An assignee, tag, record, button, closure condition, or timestamp value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a case", "operationId": "put_api_v1_cases_by_case_id", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The case name" }, "team_id": { "type": "integer", "description": "The team ID" }, "description": { "type": "string", "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status" }, "priority": { "type": "string", "description": "The case priority (maps to severity)" }, "severity": { "type": "string", "description": "The case severity (alias for priority)" }, "sub_status_id": { "type": "integer", "description": "The sub-status ID" }, "author_email": { "type": "string", "description": "Email address of the case author" }, "add_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to add" }, "remove_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to remove" }, "add_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to add" }, "remove_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to remove" }, "record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to set on the case" }, "add_record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to add" }, "remove_record_ids": { "type": "array", "items": { "type": "integer" }, "description": "Record IDs to remove" }, "team_case_buttons": { "type": "array", "items": { "type": "object" }, "description": "Array of {button_type, url, label, button_text} objects" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of {name, formula} objects" }, "metadata": { "type": "object", "description": "Metadata key-value pairs" }, "opened_at": { "type": "string", "description": "When the case was opened (ISO 8601)" }, "resolved_at": { "type": "string", "description": "When the case was resolved (ISO 8601)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_v1" } } } }, "400": { "description": "An assignee, tag, record, button, closure condition, or timestamp value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cases/{case_id}/attach_file": { "post": { "summary": "Attach a file", "operationId": "post_api_v1_cases_by_case_id_attach_file", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/files).**", "tags": [ "Cases (v1) > Files" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "The file name" }, "file_contents": { "type": "string", "description": "Base64-encoded file contents" }, "value": { "type": "string", "description": "Comment text to accompany the file" }, "author_email": { "type": "string", "description": "Email address of the author" }, "team_case_block_id": { "type": "integer", "description": "ID of a file block to attach the file to" } }, "required": [ "filename", "file_contents" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "id": { "type": "integer", "description": "The file activity ID" }, "action": { "type": "string", "description": "Type of activity" }, "value": { "type": "string", "nullable": true, "description": "Comment text" }, "user": { "$ref": "#/components/schemas/user" }, "block_id": { "type": "string", "nullable": true, "description": "The file block ID (present when team_case_block_id was supplied)" } } } } } } } } }, "/api/v1/cases/{case_id}/comment": { "post": { "summary": "Create a comment", "operationId": "post_api_v1_cases_by_case_id_comment", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/comments).**", "tags": [ "Cases (v1) > Comments" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The comment text" }, "author_email": { "type": "string", "description": "Email address of the comment author" } }, "required": [ "value" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity_v1" } } } } } } }, "/api/v1/cases/{case_id}/pdf": { "get": { "summary": "Export case as PDF", "operationId": "get_api_v1_cases_by_case_id_pdf", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases).**", "tags": [ "Cases (v1)" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "200": { "description": "PDF document of the case" } } } }, "/api/v1/cases/{case_id}/subscribe": { "post": { "summary": "Subscribe a user", "operationId": "post_api_v1_cases_by_case_id_subscribe", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/subscribers).**", "tags": [ "Cases (v1) > Subscribers" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_email": { "type": "string", "description": "Email address of the user to subscribe" } }, "required": [ "user_email" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "The case ID" }, "user": { "$ref": "#/components/schemas/user" } } } } } } } } }, "/api/v1/cases/{case_id}/unsubscribe": { "delete": { "summary": "Unsubscribe a user", "operationId": "delete_api_v1_cases_by_case_id_unsubscribe", "description": "**Deprecated since 2024-04-23. Scheduled for removal on December 1, 2026. See [replacement endpoint](https://www.tines.com/api/cases/subscribers).**", "tags": [ "Cases (v1) > Subscribers" ], "deprecated": true, "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_email": { "type": "string", "description": "Email address of the user to unsubscribe" } }, "required": [ "user_email" ] } } } }, "responses": { "204": { "description": "Empty response on success" } } } }, "/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/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/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/v2/case_inputs/{field_id}": { "delete": { "summary": "Delete a field", "operationId": "delete_api_v2_case_inputs_by_field_id", "tags": [ "Cases > Field definitions" ], "parameters": [ { "name": "field_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "patch": { "summary": "Update a field", "operationId": "patch_api_v2_case_inputs_by_field_id", "tags": [ "Cases > Field definitions" ], "parameters": [ { "name": "field_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A new field name" }, "sensitive": { "type": "boolean", "description": "Whether the sensitive field permission is required to read or write this field" }, "validation_type": { "type": "string", "enum": [ "none", "options", "regex" ], "description": "A new validation type for the field" }, "validation_options": { "type": "object", "description": "Validation options (array of values for options, regex pattern for regex)" }, "group_name": { "type": "string", "description": "The name of the group to assign the field to, or null to remove its group" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_input" } } } } } }, "put": { "summary": "Update a field", "operationId": "put_api_v2_case_inputs_by_field_id", "tags": [ "Cases > Field definitions" ], "parameters": [ { "name": "field_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A new field name" }, "sensitive": { "type": "boolean", "description": "Whether the sensitive field permission is required to read or write this field" }, "validation_type": { "type": "string", "enum": [ "none", "options", "regex" ], "description": "A new validation type for the field" }, "validation_options": { "type": "object", "description": "Validation options (array of values for options, regex pattern for regex)" }, "group_name": { "type": "string", "description": "The name of the group to assign the field to, or null to remove its group" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_input" } } } } } } }, "/api/v2/cases": { "get": { "summary": "List cases", "operationId": "get_api_v2_cases", "description": "List cases", "tags": [ "Cases" ], "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" }, { "name": "team_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by team ID" }, { "name": "filters", "in": "query", "schema": { "type": "object", "properties": { "search": { "type": "string", "description": "Free-text search across case content" }, "name": { "type": "string", "description": "Filter by case name" }, "comment": { "type": "string", "description": "Filter by comment content" }, "note": { "type": "string", "description": "Filter by note content" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED" ] }, "description": "Filter by status" }, "sub_status_names": { "type": "array", "items": { "type": "string" }, "description": "Filter by sub-status names" }, "exclude_sub_status_names": { "type": "array", "items": { "type": "string" }, "description": "Exclude sub-status names" }, "priority": { "type": "array", "items": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL", "INFO" ] }, "description": "Filter by priority" }, "exclude_priorities": { "type": "array", "items": { "type": "string" }, "description": "Exclude priorities" }, "severity": { "type": "string", "description": "Filter by severity\n\n**Deprecated. Use `priority` instead.**", "deprecated": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tag names (AND logic)\n\n**Deprecated. Use `and_tags` instead.**", "deprecated": true }, "or_tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tag names (OR logic)" }, "and_tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by tag names (AND logic)" }, "exclude_tags": { "type": "array", "items": { "type": "string" }, "description": "Exclude tag names" }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "Filter by assignee user IDs or email addresses. Use \"unassigned\" to match cases with no assignee. Cases matching any of the specified assignees will be returned." }, "and_assignees": { "type": "array", "items": { "type": "integer" }, "description": "Filter by assignee user IDs (AND logic)" }, "exclude_assignees": { "type": "array", "items": { "type": "integer" }, "description": "Exclude assignee user IDs" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Filter by assignee email addresses\n\n**Deprecated. Use `assignees` with email addresses instead.**", "deprecated": true }, "unassigned": { "type": "boolean", "description": "Filter for unassigned cases\n\n**Deprecated. Use `assignees: [\"unassigned\"]` instead.**", "deprecated": true }, "assigned_to_me": { "type": "boolean", "description": "Filter for cases assigned to current user" }, "subscribed": { "type": "boolean", "description": "Filter for cases user is subscribed to" }, "my_open_tasks": { "type": "boolean", "description": "Filter for cases with open tasks assigned to current user" }, "authors": { "type": "array", "items": { "type": "string" }, "description": "Filter by author user IDs or email addresses. Use \"tines\" to match cases created by Tines automations." }, "exclude_authors": { "type": "array", "items": { "type": "integer" }, "description": "Exclude author user IDs" }, "author_emails": { "type": "array", "items": { "type": "string" }, "description": "Filter by author email addresses\n\n**Deprecated. Use `authors` with email addresses instead.**", "deprecated": true }, "metadata": { "type": "object", "description": "Filter by metadata key-value pairs" }, "and_metadata": { "type": "object", "description": "Filter by metadata (AND logic)" }, "or_metadata": { "type": "object", "description": "Filter by metadata (OR logic)" }, "fields": { "type": "object", "description": "Filter by field values" }, "and_fields": { "type": "object", "description": "Filter by field values (AND logic)" }, "or_fields": { "type": "object", "description": "Filter by field values (OR logic)" }, "sla_status": { "type": "array", "items": { "type": "string", "enum": [ "WARNING", "EXCEEDED" ] }, "description": "Filter by SLA status" }, "and_sla_status": { "type": "array", "items": { "type": "string" }, "description": "Filter by SLA status (AND logic)" }, "exclude_sla_status": { "type": "array", "items": { "type": "string" }, "description": "Exclude SLA statuses" }, "sla_type": { "type": "array", "items": { "type": "string" }, "description": "Filter by SLA type" }, "and_sla_type": { "type": "array", "items": { "type": "string" }, "description": "Filter by SLA type (AND logic)" }, "exclude_sla_type": { "type": "array", "items": { "type": "string" }, "description": "Exclude SLA types" }, "start_date": { "type": "string", "description": "Filter by created_at start date (ISO 8601)" }, "end_date": { "type": "string", "description": "Filter by created_at end date (ISO 8601)" }, "relative_date": { "type": "string", "description": "Filter by relative date (e.g. 'last_7_days')" }, "time_range": { "type": "string", "description": "Filter by time range" }, "resolved_at_start_date": { "type": "string", "description": "Filter by resolved_at start date (ISO 8601)" }, "resolved_at_end_date": { "type": "string", "description": "Filter by resolved_at end date (ISO 8601)" }, "resolved_at_relative_date": { "type": "string", "description": "Filter by resolved_at relative date" }, "updated_at_start_date": { "type": "string", "description": "Filter by updated_at start date (ISO 8601)" }, "updated_at_end_date": { "type": "string", "description": "Filter by updated_at end date (ISO 8601)" }, "updated_at_relative_date": { "type": "string", "description": "Filter by updated_at relative date" }, "opened_at_start_date": { "type": "string", "description": "Filter by opened_at start date (ISO 8601)" }, "opened_at_end_date": { "type": "string", "description": "Filter by opened_at end date (ISO 8601)" }, "opened_at_relative_date": { "type": "string", "description": "Filter by opened_at relative date" }, "records": { "type": "array", "items": { "type": "string" }, "description": "Filter by record type names" }, "record_field": { "type": "object", "description": "Filter by record field values" }, "case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by specific case IDs" }, "child_team_ids": { "type": "array", "items": { "type": "integer" }, "description": "Filter by child team IDs" } } }, "description": "Filter criteria" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "RECENTLY_EDITED", "LEAST_RECENTLY_EDITED", "PRIORITY_ASC", "PRIORITY_DESC", "OPENED_ASC", "OPENED_DESC", "CREATED_ASC", "CREATED_DESC" ] }, "description": "Sort order" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/case" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "408": { "$ref": "#/components/responses/CaseSearchTimeout" } } }, "post": { "summary": "Create a case", "operationId": "post_api_v2_cases", "description": "Create a case", "tags": [ "Cases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The case name" }, "description": { "type": "string", "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status" }, "priority": { "type": "string", "description": "Maps to severity" }, "team_id": { "type": "integer", "description": "Team to create the case in" }, "sub_status_id": { "type": "integer", "description": "The sub-status ID" }, "template_id": { "type": "string", "description": "Template ID or slug" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees" }, "tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to apply" }, "field_values": { "type": "object", "description": "Field values as key-value pairs" }, "blocks": { "type": "array", "items": { "type": "object" }, "description": "Case blocks to create" }, "author_email": { "type": "string", "description": "Email address of the case author" }, "opened_at": { "type": "string", "description": "ISO 8601 datetime when the case was opened" }, "resolved_at": { "type": "string", "description": "ISO 8601 datetime when the case was resolved" }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata to attach to the case" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of closure condition objects with name and formula fields" }, "tasks": { "type": "array", "items": { "type": "object" }, "description": "Array of task objects with description and optional assignee_emails" } }, "required": [ "name", "team_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case" } } } }, "400": { "description": "team_id is missing, tag_names is not an array, or an assignee email is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/actions": { "get": { "summary": "List actions", "operationId": "get_api_v2_cases_by_case_id_actions", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/action" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "case_id": { "type": "integer", "description": "The case ID" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create an action", "operationId": "post_api_v2_cases_by_case_id_actions", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "action_type": { "type": "string", "description": "Action type (e.g. webhook, page)" }, "action_text": { "type": "string", "description": "Button text" }, "query_params": { "type": "object", "description": "Query parameters as key-value pairs" }, "query_param_key": { "type": "string", "description": "Single query parameter key\n\n**Deprecated. Use `query_params` instead.**", "deprecated": true }, "query_param_value": { "type": "string", "description": "Single query parameter value\n\n**Deprecated. Use `query_params` instead.**", "deprecated": true } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action" } } } }, "400": { "description": "query_params is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/actions/{id}": { "delete": { "summary": "Delete an action", "operationId": "delete_api_v2_cases_by_case_id_actions_by_id", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get an action", "operationId": "get_api_v2_cases_by_case_id_actions_by_id", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action" } } } } } }, "patch": { "summary": "Update an action", "operationId": "patch_api_v2_cases_by_case_id_actions_by_id", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "action_type": { "type": "string", "description": "Action type" }, "action_text": { "type": "string", "description": "Button text" }, "query_params": { "type": "object", "description": "Query parameters as key-value pairs" }, "query_param_key": { "type": "string", "description": "Single query parameter key\n\n**Deprecated. Use `query_params` instead.**", "deprecated": true }, "query_param_value": { "type": "string", "description": "Single query parameter value\n\n**Deprecated. Use `query_params` instead.**", "deprecated": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action" } } } }, "400": { "description": "query_params is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update an action", "operationId": "put_api_v2_cases_by_case_id_actions_by_id", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The action ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Action URL" }, "label": { "type": "string", "description": "Action label" }, "action_type": { "type": "string", "description": "Action type" }, "action_text": { "type": "string", "description": "Button text" }, "query_params": { "type": "object", "description": "Query parameters as key-value pairs" }, "query_param_key": { "type": "string", "description": "Single query parameter key\n\n**Deprecated. Use `query_params` instead.**", "deprecated": true }, "query_param_value": { "type": "string", "description": "Single query parameter value\n\n**Deprecated. Use `query_params` instead.**", "deprecated": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/action" } } } }, "400": { "description": "query_params is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/actions/batch": { "put": { "summary": "Batch update actions", "operationId": "put_api_v2_cases_by_case_id_actions_batch", "tags": [ "Cases > Actions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object" }, "description": "Array of action objects to set" } }, "required": [ "actions" ] } } } }, "responses": { "200": { "description": "Returns case_id and actions", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "actions": { "type": "array", "items": { "type": "object" }, "description": "Updated actions" } } } } } }, "400": { "description": "An action's query_params value is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/activities": { "get": { "summary": "List activities", "operationId": "get_api_v2_cases_by_case_id_activities", "tags": [ "Cases > Activities" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" }, { "name": "activity_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by activity type" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "$ref": "#/components/schemas/activity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v2/cases/{case_id}/activities/{id}": { "get": { "summary": "Get an activity", "operationId": "get_api_v2_cases_by_case_id_activities_by_id", "tags": [ "Cases > Activities" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The activity ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } } }, "/api/v2/cases/{case_id}/assignees": { "get": { "summary": "List assignees", "operationId": "get_api_v2_cases_by_case_id_assignees", "tags": [ "Cases > Assignees" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/user" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v2/cases/{case_id}/blocks": { "get": { "summary": "List blocks", "operationId": "get_api_v2_cases_by_case_id_blocks", "tags": [ "Cases > Blocks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "per_page", "in": "query", "schema": { "type": "integer" }, "description": "Number of results per page" }, { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Page number" }, { "name": "block_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by block type (note, html, file, block_group)" }, { "name": "block_group_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by parent block group ID or slug" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/block" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a block", "operationId": "post_api_v2_cases_by_case_id_blocks", "tags": [ "Cases > Blocks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "block_type": { "type": "string", "description": "Block type (note, html, file, block_group)" }, "title": { "type": "string", "description": "Block title" }, "color": { "type": "string", "enum": [ "primary", "gold", "magenta", "green", "blue", "red", "mint", "indigo", "white" ], "description": "Block color, supported on note, html, file, and block_group blocks. white and primary are interchangeable names for the default; note and html blocks report it as white and file and block_group blocks report it as primary." }, "position": { "type": "string", "description": "Position (e.g. 'top', 'bottom', or numeric)" }, "elements": { "type": "array", "items": { "type": "object" }, "description": "Initial elements" }, "hidden": { "type": "boolean", "description": "Whether the block is hidden" }, "author_email": { "type": "string", "description": "Author email address" }, "block_group_id": { "type": "string", "description": "Parent block group ID or slug" } }, "required": [ "block_type" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block" } } } } } } }, "/api/v2/cases/{case_id}/blocks/{block_id}/elements/{id}": { "get": { "summary": "Get a block element", "operationId": "get_api_v2_cases_by_case_id_blocks_by_block_id_elements_by_id", "tags": [ "Cases > Blocks > Elements" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "block_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Element ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_element" } } } } } }, "patch": { "summary": "Update a block element", "operationId": "patch_api_v2_cases_by_case_id_blocks_by_block_id_elements_by_id", "tags": [ "Cases > Blocks > Elements" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "block_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Element ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Element content" }, "color": { "type": "string", "enum": [ "white", "gold", "magenta", "green", "blue", "red", "mint", "indigo" ], "description": "Element color\n\n**Deprecated. Set `color` on the block instead, which works for every colorable block type. See [replacement endpoint](https://www.tines.com/api/cases/blocks/update).**", "deprecated": true }, "sensitive": { "type": "boolean", "description": "Whether the element is sensitive" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_element" } } } } } }, "put": { "summary": "Update a block element", "operationId": "put_api_v2_cases_by_case_id_blocks_by_block_id_elements_by_id", "tags": [ "Cases > Blocks > Elements" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "block_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Element ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Element content" }, "color": { "type": "string", "enum": [ "white", "gold", "magenta", "green", "blue", "red", "mint", "indigo" ], "description": "Element color\n\n**Deprecated. Set `color` on the block instead, which works for every colorable block type. See [replacement endpoint](https://www.tines.com/api/cases/blocks/update).**", "deprecated": true }, "sensitive": { "type": "boolean", "description": "Whether the element is sensitive" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_element" } } } } } } }, "/api/v2/cases/{case_id}/blocks/{block_id}/elements/{id}/content": { "post": { "summary": "Append content to a block element", "operationId": "post_api_v2_cases_by_case_id_blocks_by_block_id_elements_by_id_content", "tags": [ "Cases > Blocks > Elements" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "block_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Element ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Content to append" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block_element" } } } } } } }, "/api/v2/cases/{case_id}/blocks/{id}": { "delete": { "summary": "Delete a block", "operationId": "delete_api_v2_cases_by_case_id_blocks_by_id", "tags": [ "Cases > Blocks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" }, { "name": "include_children", "in": "query", "schema": { "type": "boolean" }, "description": "Whether to delete child blocks" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a block", "operationId": "get_api_v2_cases_by_case_id_blocks_by_id", "tags": [ "Cases > Blocks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block" } } } } } }, "patch": { "summary": "Update a block", "operationId": "patch_api_v2_cases_by_case_id_blocks_by_id", "tags": [ "Cases > Blocks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Block title" }, "color": { "type": "string", "enum": [ "primary", "gold", "magenta", "green", "blue", "red", "mint", "indigo", "white" ], "description": "Block color, supported on note, html, file, and block_group blocks. white and primary are interchangeable names for the default; note and html blocks report it as white and file and block_group blocks report it as primary." }, "position": { "type": "string", "description": "Block position" }, "hidden": { "type": "boolean", "description": "Whether the block is hidden" }, "block_group_id": { "type": "string", "description": "Parent block group ID, slug, or null to ungroup" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block" } } } } } }, "put": { "summary": "Update a block", "operationId": "put_api_v2_cases_by_case_id_blocks_by_id", "tags": [ "Cases > Blocks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Block ID or slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Block title" }, "color": { "type": "string", "enum": [ "primary", "gold", "magenta", "green", "blue", "red", "mint", "indigo", "white" ], "description": "Block color, supported on note, html, file, and block_group blocks. white and primary are interchangeable names for the default; note and html blocks report it as white and file and block_group blocks report it as primary." }, "position": { "type": "string", "description": "Block position" }, "hidden": { "type": "boolean", "description": "Whether the block is hidden" }, "block_group_id": { "type": "string", "description": "Parent block group ID, slug, or null to ungroup" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/block" } } } } } } }, "/api/v2/cases/{case_id}/comments": { "get": { "summary": "List comments", "operationId": "get_api_v2_cases_by_case_id_comments", "tags": [ "Cases > Comments" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/activity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" }, "case_id": { "type": "integer", "description": "The case ID" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a comment", "operationId": "post_api_v2_cases_by_case_id_comments", "tags": [ "Cases > Comments" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Comment text" }, "author_email": { "type": "string", "description": "Email of comment author" } }, "required": [ "value" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } } }, "/api/v2/cases/{case_id}/comments/{id}": { "delete": { "summary": "Delete a comment", "operationId": "delete_api_v2_cases_by_case_id_comments_by_id", "tags": [ "Cases > Comments" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a comment", "operationId": "get_api_v2_cases_by_case_id_comments_by_id", "tags": [ "Cases > Comments" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } }, "patch": { "summary": "Update a comment", "operationId": "patch_api_v2_cases_by_case_id_comments_by_id", "tags": [ "Cases > Comments" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Updated comment text" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } }, "put": { "summary": "Update a comment", "operationId": "put_api_v2_cases_by_case_id_comments_by_id", "tags": [ "Cases > Comments" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Updated comment text" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } } }, "/api/v2/cases/{case_id}/comments/{id}/reactions": { "delete": { "summary": "Remove a reaction", "operationId": "delete_api_v2_cases_by_case_id_comments_by_id_reactions", "tags": [ "Cases > Comments > Reactions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "description": "Emoji character to remove" } }, "required": [ "emoji" ] } } } }, "responses": { "204": { "description": "Empty response on success" } } }, "post": { "summary": "Add a reaction", "operationId": "post_api_v2_cases_by_case_id_comments_by_id_reactions", "tags": [ "Cases > Comments > Reactions" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The comment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "description": "Emoji character" } }, "required": [ "emoji" ] } } } }, "responses": { "201": { "description": "Reaction added" } } } }, "/api/v2/cases/{case_id}/fields": { "get": { "summary": "List fields", "operationId": "get_api_v2_cases_by_case_id_fields", "tags": [ "Cases > Fields" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/field" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create or set a field value", "operationId": "post_api_v2_cases_by_case_id_fields", "tags": [ "Cases > Fields" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input_id": { "type": "integer", "description": "The field definition ID" }, "value": { "type": "string", "description": "The field value" } }, "required": [ "input_id", "value" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/field" } } } } } } }, "/api/v2/cases/{case_id}/fields/{id}": { "delete": { "summary": "Delete a field value", "operationId": "delete_api_v2_cases_by_case_id_fields_by_id", "tags": [ "Cases > Fields" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field value ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a field", "operationId": "get_api_v2_cases_by_case_id_fields_by_id", "tags": [ "Cases > Fields" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field value ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/field" } } } } } }, "patch": { "summary": "Update a field value", "operationId": "patch_api_v2_cases_by_case_id_fields_by_id", "tags": [ "Cases > Fields" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field value ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The field value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/field" } } } } } }, "put": { "summary": "Update a field value", "operationId": "put_api_v2_cases_by_case_id_fields_by_id", "tags": [ "Cases > Fields" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The field value ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "The field value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/field" } } } } } } }, "/api/v2/cases/{case_id}/files": { "get": { "summary": "List files", "operationId": "get_api_v2_cases_by_case_id_files", "tags": [ "Cases > Files" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/activity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Attach a file", "operationId": "post_api_v2_cases_by_case_id_files", "tags": [ "Cases > Files" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "File name" }, "file_contents": { "type": "string", "description": "Base64-encoded file contents" }, "value": { "type": "string", "description": "Optional annotation/comment" }, "author_email": { "type": "string", "description": "Email of file uploader" }, "team_case_block_id": { "type": "integer", "description": "Block ID to attach file to" } }, "required": [ "filename", "file_contents" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } } }, "/api/v2/cases/{case_id}/files/{file_id}/download": { "get": { "summary": "Download a file", "operationId": "get_api_v2_cases_by_case_id_files_by_file_id_download", "tags": [ "Cases > Files" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "file_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The file ID" } ], "responses": { "200": { "description": "Binary file content with appropriate Content-Type header" } } } }, "/api/v2/cases/{case_id}/files/{file_id}/info": { "get": { "summary": "Get file info", "operationId": "get_api_v2_cases_by_case_id_files_by_file_id_info", "tags": [ "Cases > Files" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "file_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The file ID" } ], "responses": { "200": { "description": "File metadata and base64-encoded contents", "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "Original file name" }, "content_type": { "type": "string", "description": "MIME type of the file" }, "guid": { "type": "string", "description": "Signed ID of the file blob" }, "md5": { "type": "string", "description": "MD5 checksum" }, "sha256": { "type": "string", "description": "SHA-256 hash of the checksum" }, "sizeinbytes": { "type": "integer", "description": "File size in bytes" }, "base64encodedcontents": { "type": "string", "description": "Base64-encoded file contents" } } } } } }, "404": { "description": "The case is not visible to the API key, no action on the case matches file_id, or that action has no attached file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/files/{id}": { "delete": { "summary": "Delete a file", "operationId": "delete_api_v2_cases_by_case_id_files_by_id", "tags": [ "Cases > Files" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The file ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a file", "operationId": "get_api_v2_cases_by_case_id_files_by_id", "tags": [ "Cases > Files" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The file ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } } }, "/api/v2/cases/{case_id}/linked_cases": { "get": { "summary": "List linked cases", "operationId": "get_api_v2_cases_by_case_id_linked_cases", "tags": [ "Cases > Linked Cases" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "linked_cases": { "type": "array", "items": { "$ref": "#/components/schemas/linked_case" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Link a case", "operationId": "post_api_v2_cases_by_case_id_linked_cases", "tags": [ "Cases > Linked Cases" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linked_case_id": { "type": "integer", "description": "ID of case to link" } }, "required": [ "linked_case_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_case" } } } } } } }, "/api/v2/cases/{case_id}/linked_cases/{id}": { "delete": { "summary": "Unlink a case", "operationId": "delete_api_v2_cases_by_case_id_linked_cases_by_id", "tags": [ "Cases > Linked Cases" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the linked case to remove" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v2/cases/{case_id}/linked_cases/batch": { "post": { "summary": "Link multiple cases", "operationId": "post_api_v2_cases_by_case_id_linked_cases_batch", "tags": [ "Cases > Linked Cases" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linked_case_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of case IDs to link" } }, "required": [ "linked_case_ids" ] } } } }, "responses": { "201": { "description": "Returns linked cases", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked_cases": { "type": "array", "items": { "type": "object" }, "description": "Newly linked cases" } } } } } } } } }, "/api/v2/cases/{case_id}/metadata": { "delete": { "summary": "Delete metadata", "operationId": "delete_api_v2_cases_by_case_id_metadata", "tags": [ "Cases > Metadata" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "string" }, "description": "Keys to delete (omit to delete all)" } } } } } }, "responses": { "204": { "description": "Empty response on success" }, "400": { "description": "metadata is not an array of keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List metadata", "operationId": "get_api_v2_cases_by_case_id_metadata", "tags": [ "Cases > Metadata" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/metadata" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Set metadata", "operationId": "post_api_v2_cases_by_case_id_metadata", "tags": [ "Cases > Metadata" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "description": "Key-value pairs to set" } }, "required": [ "metadata" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } }, "400": { "description": "metadata is missing, empty, or is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "One of the keys in the request already has a value on the case. This endpoint only creates keys; use the update endpoint to change an existing key. The check is per key, so a batch containing one existing key sets none of them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update metadata", "operationId": "put_api_v2_cases_by_case_id_metadata", "tags": [ "Cases > Metadata" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "description": "Key-value pairs to update" } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } }, "400": { "description": "metadata is missing, empty, or is not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/metadata/{id}": { "get": { "summary": "Get metadata by key", "operationId": "get_api_v2_cases_by_case_id_metadata_by_id", "tags": [ "Cases > Metadata" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Metadata key" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata" } } } } } } }, "/api/v2/cases/{case_id}/notes": { "get": { "summary": "List notes", "operationId": "get_api_v2_cases_by_case_id_notes", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/note" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a note", "operationId": "post_api_v2_cases_by_case_id_notes", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Note content" }, "title": { "type": "string", "description": "Note title" }, "color": { "type": "string", "description": "Note color" }, "sensitive": { "type": "boolean", "description": "Whether the note is sensitive" }, "hidden": { "type": "boolean", "description": "Whether the note is hidden" }, "author_email": { "type": "string", "description": "Author email address" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } } }, "/api/v2/cases/{case_id}/notes/{id}": { "delete": { "summary": "Delete a note", "operationId": "delete_api_v2_cases_by_case_id_notes_by_id", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The note ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a note", "operationId": "get_api_v2_cases_by_case_id_notes_by_id", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The note ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } }, "patch": { "summary": "Update a note", "operationId": "patch_api_v2_cases_by_case_id_notes_by_id", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The note ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Note content" }, "title": { "type": "string", "description": "Note title" }, "color": { "type": "string", "description": "Note color" }, "sensitive": { "type": "boolean", "description": "Whether the note is sensitive" }, "hidden": { "type": "boolean", "description": "Whether the note is hidden" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } }, "put": { "summary": "Update a note", "operationId": "put_api_v2_cases_by_case_id_notes_by_id", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The note ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Note content" }, "title": { "type": "string", "description": "Note title" }, "color": { "type": "string", "description": "Note color" }, "sensitive": { "type": "boolean", "description": "Whether the note is sensitive" }, "hidden": { "type": "boolean", "description": "Whether the note is hidden" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } } }, "/api/v2/cases/{case_id}/notes/{id}/content": { "post": { "summary": "Append content to a note", "operationId": "post_api_v2_cases_by_case_id_notes_by_id_content", "tags": [ "Cases > Notes" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The note ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Content to append" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } } }, "/api/v2/cases/{case_id}/pdf": { "get": { "summary": "Export case as PDF", "operationId": "get_api_v2_cases_by_case_id_pdf", "tags": [ "Cases" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "200": { "description": "PDF document of the case" } } } }, "/api/v2/cases/{case_id}/records": { "get": { "summary": "List records", "operationId": "get_api_v2_cases_by_case_id_records", "tags": [ "Cases > Records" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/record" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Attach a record to a case", "operationId": "post_api_v2_cases_by_case_id_records", "tags": [ "Cases > Records" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_result_set_id": { "type": "integer", "description": "Record result set ID to attach" } }, "required": [ "record_result_set_id" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record" } } } } } } }, "/api/v2/cases/{case_id}/records/{id}": { "delete": { "summary": "Remove a record from a case", "operationId": "delete_api_v2_cases_by_case_id_records_by_id", "tags": [ "Cases > Records" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a record", "operationId": "get_api_v2_cases_by_case_id_records_by_id", "tags": [ "Cases > Records" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The record ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/record" } } } } } } }, "/api/v2/cases/{case_id}/subscribers": { "get": { "summary": "List subscribers", "operationId": "get_api_v2_cases_by_case_id_subscribers", "tags": [ "Cases > Subscribers" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/subscriber" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Subscribe a user", "operationId": "post_api_v2_cases_by_case_id_subscribers", "tags": [ "Cases > Subscribers" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_email": { "type": "string", "description": "Email of user to subscribe" } }, "required": [ "user_email" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscriber" } } } } } } }, "/api/v2/cases/{case_id}/subscribers/{id}": { "delete": { "summary": "Unsubscribe a user", "operationId": "delete_api_v2_cases_by_case_id_subscribers_by_id", "tags": [ "Cases > Subscribers" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Subscriber ID" } ], "responses": { "204": { "description": "Empty response on success" } } } }, "/api/v2/cases/{case_id}/subscribers/batch": { "post": { "summary": "Subscribe multiple users", "operationId": "post_api_v2_cases_by_case_id_subscribers_batch", "tags": [ "Cases > Subscribers" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_emails": { "type": "array", "items": { "type": "string" }, "description": "Array of email addresses" } }, "required": [ "user_emails" ] } } } }, "responses": { "201": { "description": "Returns subscribers", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "integer", "description": "Case ID" }, "subscribers": { "type": "array", "items": { "type": "object" }, "description": "Newly subscribed users" } } } } } }, "400": { "description": "user_emails is not an array of strings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/tasks": { "get": { "summary": "List tasks", "operationId": "get_api_v2_cases_by_case_id_tasks", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "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": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create a task", "operationId": "post_api_v2_cases_by_case_id_tasks", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Task description" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees" } }, "required": [ "description" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/task" } } } }, "400": { "description": "An assignee email does not identify a visible user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The task failed validation, for example the description is blank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/tasks/{id}": { "delete": { "summary": "Delete a task", "operationId": "delete_api_v2_cases_by_case_id_tasks_by_id", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The task ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a task", "operationId": "get_api_v2_cases_by_case_id_tasks_by_id", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The task ID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/task" } } } } } }, "patch": { "summary": "Update a task", "operationId": "patch_api_v2_cases_by_case_id_tasks_by_id", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The task ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Task description" }, "completed": { "type": "boolean", "description": "Whether the task is completed" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/task" } } } }, "400": { "description": "An assignee email does not identify a visible user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a task", "operationId": "put_api_v2_cases_by_case_id_tasks_by_id", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The task ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Task description" }, "completed": { "type": "boolean", "description": "Whether the task is completed" }, "assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/task" } } } }, "400": { "description": "An assignee email does not identify a visible user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{case_id}/tasks/batch": { "post": { "summary": "Create multiple tasks", "operationId": "post_api_v2_cases_by_case_id_tasks_batch", "tags": [ "Cases > Tasks" ], "parameters": [ { "name": "case_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object" }, "description": "Array of {description, assignee_emails} objects" } }, "required": [ "tasks" ] } } } }, "responses": { "201": { "description": "Returns created tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object" }, "description": "Created tasks" } } } } } }, "400": { "description": "tasks is missing, empty, malformed, exceeds the batch limit, or contains an invalid assignee email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{id}": { "delete": { "summary": "Delete a case", "operationId": "delete_api_v2_cases_by_id", "description": "Delete a case", "tags": [ "Cases" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "responses": { "204": { "description": "Empty response on success" } } }, "get": { "summary": "Get a case", "operationId": "get_api_v2_cases_by_id", "description": "Get a case", "tags": [ "Cases" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" }, { "name": "resolve_mentions", "in": "query", "schema": { "type": "string" }, "description": "Set to 'true' to resolve @mentions to display names" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case" } } } } } }, "patch": { "summary": "Update a case", "operationId": "patch_api_v2_cases_by_id", "description": "Update a case", "tags": [ "Cases" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The case name" }, "description": { "type": "string", "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status" }, "priority": { "type": "string", "description": "The case priority" }, "team_id": { "type": "integer", "description": "The team ID" }, "sub_status_id": { "type": "integer", "description": "The sub-status ID" }, "add_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to add" }, "remove_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to remove" }, "add_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to add" }, "remove_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to remove" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of closure condition objects with name and formula fields" }, "author_email": { "type": "string", "description": "Email address of the case author" }, "opened_at": { "type": "string", "description": "ISO 8601 datetime when the case was opened" }, "resolved_at": { "type": "string", "description": "ISO 8601 datetime when the case was resolved" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case" } } } }, "400": { "description": "An assignee, tag, closure condition, or timestamp value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update a case", "operationId": "put_api_v2_cases_by_id", "description": "Update a case", "tags": [ "Cases" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The case name" }, "description": { "type": "string", "description": "The case description" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "The case status" }, "priority": { "type": "string", "description": "The case priority" }, "team_id": { "type": "integer", "description": "The team ID" }, "sub_status_id": { "type": "integer", "description": "The sub-status ID" }, "add_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to add" }, "remove_assignee_emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of assignees to remove" }, "add_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to add" }, "remove_tag_names": { "type": "array", "items": { "type": "string" }, "description": "Tag names to remove" }, "closure_conditions": { "type": "array", "items": { "type": "object" }, "description": "Array of closure condition objects with name and formula fields" }, "author_email": { "type": "string", "description": "Email address of the case author" }, "opened_at": { "type": "string", "description": "ISO 8601 datetime when the case was opened" }, "resolved_at": { "type": "string", "description": "ISO 8601 datetime when the case was resolved" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case" } } } }, "400": { "description": "An assignee, tag, closure condition, or timestamp value is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/{id}/description": { "post": { "summary": "Append to case description", "operationId": "post_api_v2_cases_by_id_description", "description": "Append to case description", "tags": [ "Cases" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The case ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Text to append to the case description" } }, "required": [ "description" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case" } } } }, "400": { "description": "description is missing or empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/cases/bulk/fields": { "post": { "summary": "Bulk update fields across cases", "operationId": "post_api_v2_cases_bulk_fields", "tags": [ "Cases > Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object" }, "description": "Array of {case_id, input_id, value} objects" } }, "required": [ "fields" ] } } } }, "responses": { "201": { "description": "Returns updated field values", "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object" }, "description": "Updated field values" } } } } } }, "400": { "description": "case_ids or fields is missing, empty, or is not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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}/cases": { "get": { "summary": "List a record's cases", "operationId": "get_api_v2_records_by_id_cases", "description": "List the cases linked to the given record, oldest first. Results are keyset-paginated.", "tags": [ "Records" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "The 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": "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" } } } }, "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": 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" } ], "page": {} } } } } } } }, "/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." }, "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." } }, "responses": { "BadRequest": { "description": "The request was malformed, or a parameter failed validation.", "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" } } } }, "CaseSearchTimeout": { "description": "The search timed out, which deep pagination can cause. Retrying the same page resumes from where this request stopped rather than starting over.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InvalidTagColor": { "description": "color is neither one of the named colors nor a #RRGGBB hex value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }