# Tines API ## Welcome The REST API exposes a number of endpoints providing programmatic access to Tines data and functionality. ## Accessing the API The REST API takes the form of the following URL: `https:///api/v1/`. For ``, you can copy the domain visible in your web browser when you're navigating the Tines UI. For cloud users this will be similar to either `adjective-noun-1234.tines.io` or `adjective-noun-1234.tines.com`. ## Pagination Requests that return multiple items, e.g.: events and actions, will be paginated to 20 items by default. You can specify further pages with the `?page` parameter. In addition, you can set a custom page size with the `?per_page` parameter. ``` curl 'https:///api/v1/events?page=2&per_page=100' ``` ### The 'meta' object When pagination of items occurs, an object named "meta" will be included in the response body. This object contains the following information: - `current_page`: A link to the current page of results. - `previous_page`: A link to the previous page of results (if available). - `next_page`: A link to the next page of results (if available). - `next_page_number`: The next page number to facilitate easier navigation through the results. - `per_page`: The number of items returned per page (defaults to 20, maximum is 500). - `pages`: The number of pages available. - `count`: The total number of items returned by the request. A sample response including the meta object is shown below: ```json { "agents": [...], "meta": { "current_page": "https:///api/v1/agents?page=1&per_page=20", "previous_page": null, "next_page": "https:///api/v1/agents?page=2&per_page=20", "next_page_number": 2, "per_page": 20, "pages": 13, "count": 242 } } ``` ### HTTP Status codes You can configure your clients to treat the HTTP Responses Codes returned by Tines API as follows: - Treat 200–299 as success - Treat 400–499 as client request errors - Treat 500–599 as Tines server errors Most 400-level errors and some 500-level errors will include a body in the response containing more information about why the error was returned. ## Authentication and Authorization All requests to the Tines REST API require authentication. ## Generate API Key To generate an API key in Tines, use the [Tines connect flow](https://www.tines.com/docs/credentials/connect-flows/tines). - Navigate to the team that will be using the API and click **Credentials**. - Click **+ New Credential** and select **Tines** and follow the prompts to connect. To learn more about connect flows generally, see our [docs](https://www.tines.com/docs/credentials/connect-flows). ## View API Keys From the Tines settings page, select "API keys" under "Access & security". ![Navigation](https://www.datocms-assets.com/55802/1764675719-api_keys_settings_page.png) On the API Keys page you can view all of the API keys you have access to or create a new key. While you can create a new key manually from this page, using the [Tines connect flow](https://www.tines.com/docs/credentials/connect-flows/tines) is recommended. Tines has four types of API keys: - Personal API keys are linked to your user account, and have access to all items that you do. Operations performed using one of these keys will be recorded as being performed by you. Only you have access to create and delete your personal keys. - Service API keys are linked to separate service account users, and can be granted access to any tenant permissions such as `AUDIT_LOG_READ` and `TUNNEL_MANAGE` by a tenant owner. Operations performed using one of these keys will be recorded as being performed by the associated service account user. - Tenant owner API keys are linked to separate service account users, and have full Owner access to the entire tenant. Operations performed using one of these keys will be recorded as being performed by the associated service account user. Tenant Owners have access to create and delete all tenant keys. - Team API keys are also linked to separate service account users, but they have role-based access to a specific team on the tenant. Operations performed using one of these keys will be recorded as being performed by the associated service account user. Tenant Owners have access to create and delete all team keys. If you use an underprivileged API key to access a protected resource the key does not have permissions for, you will get a `404: Not Found` response. ## Using an API Key Each request sent to the REST API must be authenticated using an API key, included in the `X-User-Token` header. For example: ```bash curl -X GET https:///api/v1/events/ \ -H 'content-type: application/json' \ -H 'x-user-token: <>' ``` ### Bearer/Token Authentication Our API includes support for Bearer/Token Authentication. To authenticate using this method, simply include your API token in the `Authorization` header of your requests, prefixed with "Bearer" and a single space. For example: ```bash curl -X GET https:///api/v1/events/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## API rate limits Most APIs have a limit of 5000 per minute. The following rate limits apply to specific API endpoints. | Endpoint | Requests/Minute | | ------------- | --------------- | | actions | 100 | | admin/users | 500 | | audit_logs | 1000 | | records | 400 | | tokens (auth) | 2500 | _Note: These limits are enforced per IP address and API token combination._ ## Audit logs We automatically capture an audit log any time a user changes any piece of data in your Tines tenant. These audit logs are available to tenant admins via our API, and are typically drained to a log analysis or SIEM tool for further investigation. ## Logged operations For every operation available in the user interface and API, our system automatically and consistently captures a log. | Operation | Description | | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | | ActionDescriptionChange | An Action's description was changed | | ActionEgressControlRuleChange | An action egress control rule was changed | | ActionEgressControlRuleCreation | An action egress control rule was created | | ActionEgressControlRuleDeletion | An action egress control rule was deleted | | ActionInputAddition | An Action input was added | | ActionInputIsCollapsedChange | An Action input was collapsed | | ActionInputOptionsUpdate | An Action input's options were updated | | ActionInputRemoval | An Action input was removed | | ActionInputReorder | An Action input was reordered | | ActionInputUpdate | An Action input was updated | | ActionInputValueUpdate | An Action input value was updated | | ActionIntegrationCreation | An Action integration was created | | ActionIntegrationRemoval | An Action integration was removed | | ActionLogsClearance | An Action's logs were cleared | | ActionMemoryClearance | An Action's memory was cleared | | ActionMemoryRelease | An Action's memory was released | | ActionMetricsChange | An Action's time-saved/reporting setting was changed | | ActionPublicTemplateDisconnect | An Action was disconnected from a public template | | ActionRecordTypeChange | An Action's record type was changed | | ActionRerun | An Action was rerun | | ActionRun | An Action was run | | ActionSizeChange | An actions size was changed | | ActionTeamCaseTemplateUpdate | An Action's team case template was updated | | ActionTest | An Action was tested | | ActionsDisabledChange | Multiple Actions had their 'disabled' property changed | | ActionsEventsDeletion | Multiple Actions' events were cleared | | ActionsLogsClearance | Multiple Actions' logs were cleared | | ActionsMonitoringChange | Multiple Actions' monitoring settings were changed | | ActionsNameChange | Multiple Actions' names were changed | | ActionsOptionsChange | Multiple Actions' options were changed | | ActionsScheduleChange | Multiple Actions' schedules were changed | | AiActionConversationCancellation | An AI action conversation was cancelled | | AiActionConversationDeletion | An AI action conversation was deleted | | AiCustomModelsChange | AI custom models were changed | | AiProviderModelChange | AI provider model was changed | | AnalyticsCapture | An analytics event was captured | | AnnotationContentChange | An annotation was edited | | AnnotationSizeChange | An annotation was resized | | ApplyPageTemplate | A page template was applied | | ArchivedStoryDeleteAll | A team's story trash was emptied | | ArchivedStoryDeletion | An individual story was removed from a team's story trash | | AuthenticationTokenCreation | A new API key was created | | AuthenticationTokenDeletion | An API key was deleted | | AuthenticationTokenEdit | An API key was edited | | BatchStoryArchive | A set of stories were moved to trash | | BoardColumnReorder | A board column was reordered | | BoardColumnVisibility | A board column's visibility was changed | | CredentialBulkDestruction | Multiple credentials were deleted | | CredentialDestruction | A credential was deleted | | CredentialIconChange | A credential's icon was changed | | CredentialMetadataReplacement | A credential's metadata was replaced | | CredentialMetadataToResourceReplacement | A credential's metadata was replaced with a resource | | CredentialMovement | A credential was moved to a new team/folder | | CredentialOauthTokenRefresh | An OAuth credential's token was refreshed | | CredentialReplacement | A credential was replaced on a story | | CredentialSave | A credential was created or updated | | CredentialTest | A credential was tested | | CustomCertificateAuthorityCreation | A custom certificate authority was created | | CustomCertificateAuthorityDeletion | A custom certificate authority was deleted | | CustomCertificateAuthoritySet | A custom certificate authority was set | | CustomTeamRoleCreation | A custom team role was created | | CustomTeamRoleDestruction | A custom team role was destroyed | | CustomTeamRoleUpdate | A custom team role was updated | | DashboardChartCreation | A dashboard chart was created | | DashboardCreation | A dashboard was created | | DashboardDeletion | A dashboard was deleted | | DashboardDuplicate | A dashboard was duplicated | | DashboardElementCreation | A dashboard element was created | | DashboardElementDeletion | A dashboard element was deleted | | DashboardListCreation | A dashboard list was created | | DashboardListUpdate | A dashboard list was updated | | DashboardNoteCreation | A dashboard note was created | | DashboardNoteUpdate | A dashboard note was updated | | DashboardSubscriptionCreate | A dashboard subscription was created | | DashboardSubscriptionUpdate | A dashboard subscription was updated | | DashboardUpdate | A dashboard was updated | | DraftCredentialCreation | A draft credential was created | | DraftStoryCreation | A draft story was created | | DraftStoryDeletion | A draft story was deleted | | DraftStoryRebase | A draft story was rebased | | DraftStoryReset | A draft story was reset | | EventDeletion | An event was deleted | | EventLimitSettingCreation | An event limit setting was created | | EventLimitSettingDeletion | An event limit setting was deleted | | EventLimitSettingUpdate | An event limit setting was updated | | EventLimitUserSubscriberCreation | An event limit user subscriber was created | | EventLimitUserSubscriberDeletion | An event limit user subscriber was deleted | | EventLimitWebhookSubscriberCreation | An event limit webhook subscriber was created | | EventLimitWebhookSubscriberDeletion | An event limit webhook subscriber was deleted | | EventReEmission | An event was re-emitted | | ExampleStoryImport | A story was imported from the story library | | FolderCreation | A folder was created | | FolderDestruction | A folder was destroyed | | FolderUpdate | A folder was updated | | FormFieldAddition | A form field was added | | FormFieldDuplication | A form field was duplicated | | FormFieldRemoval | A form field was removed | | FormFieldReorder | A form field's position was reordered | | FormFieldUpdate | A form field was updated | | FormUpdate | A form was updated | | GlobalResourceCreation | A global resource was created | | GlobalResourceDestruction | A global resource was deleted | | GlobalResourceEdit | A global resource was edited | | GlobalResourceMovement | A global resource was moved to a new team/folder | | GroupExtraction | A group was extracted from a set of actions | | GroupFlatten | A group was flattened to a set of actions | | IntegrationSelection | An integration was selected | | IntegrationSelectionUndo | An integration selection was undone | | IPAccessControlRuleChange | An IP access control rule was changed | | IPAccessControlRuleCreation | An IP access control rule was created | | IPAccessControlRuleDeletion | An IP access control rule was deleted | | JobsQueuedDeletion | Currently enqueued jobs were cleared (for a self-hosted tenant) | | JobsRetryingDeletion | Currently retrying jobs were cleared (for a self-hosted tenant) | | LastEventReEmission | The most recent event was re-emitted | | LicenseApplication | A license was applied | | LicenseValidation | A license was validated | | LinkChange | A link between actions was edited | | Login | A user logged in | | LoginNoticeChange | Login notice was changed | | MergePageElementContainers | Page element containers were merged | | MoveFormFieldToExistingContainer | A form field was moved to an existing container | | MoveFormFieldToNewContainer | A form field was moved to a new container | | NotificationBulkDeletion | Multiple notifications were deleted | | NotificationBulkRead | Multiple notifications were marked as read | | NotificationDeletion | A notification was deleted | | NotificationIsReadChange | A notification's read status was changed | | NotificationSettingSave | A notification setting was saved | | OnboardingFormSubmission | Onboarding form was submitted | | PageCollectionCreation | A page collection was created | | PageCollectionDestruction | A page collection was destroyed | | PageCollectionPageMove | A page collection page was moved | | PageCollectionPageRemove | A page was removed from a page collection | | PageCollectionPagesAdd | Pages were added to a page collection | | PageCollectionReorder | A page collection was reordered | | PageCollectionUpdate | A page collection was updated | | PageDisplayLogoSet | A page display logo was set | | PageElementButtonGroupToggle | A page element button group was toggled | | PageElementClearance | Page elements were cleared | | PageElementConditionRuleCreation | A page element condition rule was created | | PageElementConditionRuleDestruction | A page element condition rule was destroyed | | PageElementConditionRuleUpdate | A page element condition rule was updated | | PageElementConditionUpdate | A page element condition was updated | | PageElementContainerAddition | A page element container was added | | PageElementContainerDuplication | A page element container was duplicated | | PageElementContainerRemoval | A page element container was removed | | PageElementContainerReplaceElements | Page element container elements were replaced | | PageElementContainerUpdate | A page element container was updated | | PageEmojiSet | A page emoji was set | | PageLogoCreation | A page logo was created | | PageLogoSet | A page logo was set | | PageSsoGroupsUpdate | Page SSO groups were updated | | PageThemeApplication | A page theme was applied | | PageThemeCreation | A page theme was created | | PageThemeDestruction | A page theme was destroyed | | PreviewPageTemplate | A page template was previewed | | RecordBulkDeletion | Multiple records were deleted | | RecordElementExportRequest | A record element export was requested | | RecordReportClone | A record report was cloned | | RecordReportCreation | A Record report was created | | RecordReportDeletion | A Record report was deleted | | RecordReportElementColumnReorder | A Record report element column was reordered | | RecordReportElementCreation | A Record report element was created | | RecordReportElementDestruction | A Record report element was deleted | | RecordReportElementUpdate | A Record report element was edited | | RecordReportFiltersUpdate | A record report's filters were updated | | RecordReportUpdate | A Record report was edited | | RecordResultSetCreate | A record result set was created | | RecordResultSetDestruction | A record result set was destroyed | | RecordResultSetUpdate | A Record result set was updated | | RecordTypeCreation | A Record type was created | | RecordTypeDestruction | A Record type was deleted | | RecordTypeUpdate | A Record type was updated | | RecordWriterCreation | A Record writer was created | | RecordWriterDestruction | A Record writer was deleted | | RecordWriterUpdate | A Record writer was edited | | ResourceIconChange | A resource's icon was changed | | ResourceLockedUpdate | A resource's locked status was updated | | ResourceReplacement | A global resource was replaced on a story | | ResourceToCredentialMetadataReplacement | A resource was replaced with credential metadata | | RunActionWithReceivedEvent | An action was run with a received event | | SavedStoryRunModification | A saved story run was modified | | SCIM/2.0/User/{operation} | A SCIM 2.0 operation (create, replace, update or destroy) on a User | | SenderEmailAddressCreation | A sender email address was created | | SenderEmailAddressDeletion | A sender email address was deleted | | SharedObjectLinkCreation | A shared object link was created | | SharedObjectLinkUpdate | A shared object link was updated | | SharedObjectLinkViewSave | A shared object link view was saved | | SmtpConfigurationTest | An SMTP configuration was tested | | SsoConfigurationDefaultSet | The default SSO configuration was set to Tines-powered | | SsoConfigurationJitConfigurationSet | The SSO JIT configuration was set | | SsoConfigurationOidcSet | The default SSO configuration was set to OIDC | | SsoConfigurationPageGroupAttributeNameUpdate | The SSO page group attribute name was updated | | SsoConfigurationSamlSet | The default SSO configuration was set to SAML | | StoryActionsAutoAlign | A set of actions were auto aligned | | StoryActionsAutoLayout | A set of actions were auto laid-out | | StoryActionsPositioning | A set of actions and annotations were repositioned | | StoryAPIChange | Enable webhook API responses on a story | | StoryArchive | A story was moved to trash | | StoryChangeRequestApproval | A story change request was approved | | StoryChangeRequestCancellation | A story change request was cancelled | | StoryChangeRequestCreation | A story change request was created | | StoryChangeRequestPromotion | A story change request was promoted | | StoryContainerFavoritedChange | A story container's favorited status was changed | | StoryContainerOwnerDelete | A story container owner was deleted | | StoryContainerOwnerUpdate | A story container owner was updated | | StoryContainerSubscriberCreation | A story container subscriber was created | | StoryContainerSubscriberDeletion | A story container subscriber was deleted | | StoryCreation | A story was created | | StoryDataDeletion | A story's data was deleted | | StoryDescriptionChange | A story's description was changed | | StoryDisabledChange | A story was disabled or enabled | | StoryEventsDeletion | All of a story's events were deleted | | StoryIconChange | A story's icon was changed | | StoryImport | A story was imported | | StoryIntegrationFieldsUpdate | A story's integration fields were updated | | StoryItemsCreation | A set of actions/annotations were created | | StoryItemsDestruction | A set of actions/annotations were destroyed | | StoryItemsMovement | A set of actions/annotations were moved | | StoryJobsClearance | A story's scheduled jobs were cleared | | StoryKeepEventsForChange | A story's event retention settings were changed | | StoryLegacyUnpublish | A legacy story was unpublished | | StoryLibraryMetadataChange | A story library's metadata was changed | | StoryLLMProductInstructionsChange | A story's LLM product instructions were changed | | StoryLockedChange | A story was locked or unlocked | | StoryMetricsChange | A story's metrics were changed | | StoryMonitoringChange | A story's monitoring settings were changed | | StoryMovement | A story was moved | | StoryNameChange | A story's name was changed | | StoryOnboardingFinish | Story onboarding was finished | | StoryOnboardingStart | Story onboarding was started | | StoryOnboardingUnpause | Story onboarding was unpaused | | StoryPriorityChange | A story's priority was changed | | StoryRecipientAddition | A monitoring recipient was added for a story | | StoryRecipientRemoval | A monitoring recipient was removed for a story | | StoryRecipientUpdate | A monitoring recipient was changed for a story | | StoryReportingStatusChange | Reporting was enabled/disabled for a story | | StoryRequireStoryOwnerApprovalUpdate | Story owner approval requirement was updated | | StoryRestore | A story was restored from the trash | | StoryRunMockPayloadMappingCreation | A story run mock payload mapping was created | | StoryRunMockPayloadMappingDeletion | A story run mock payload mapping was deleted | | StoryRunSaveSettingModification | A story run save setting was modified | | StorySendToStoryChange | A story's send-to-story settings were edited | | StoryTagsUpdate | A story's tags were updated | | StoryVersionCreate | A story version was created | | StoryVersionDeletion | A story version was deleted | | StoryVersionImport | A story version was imported | | StoryVersionNameChange | A story's version was renamed | | StoryViewSave | A story view was saved | | SyncDestinationDeletion | A sync destination was deleted | | SyncDestinationManualSync | A sync destination was manually synced | | SyncDestinationSave | A sync destination was saved | | SyncedStoryDetach | A synced story was detached | | TagChange | A tag was changed | | TagCreation | A tag was created | | TagDeletion | A tag was deleted | | TeamAllocationChange | A team's allocation was changed | | TeamCaseAddCommentReaction | A reaction was added to a case comment | | TeamCaseBlockCreation | A team case block was created | | TeamCaseBlockDeletion | A team case block was deleted | | TeamCaseBlockElementUpdate | A team case block element was updated | | TeamCaseBlockUpdate | A team case block was updated | | TeamCaseBoardMovement | A team case board movement occurred | | TeamCaseBulkCommentCreation | Comments were bulk created on team cases | | TeamCaseBulkDeletion | Team cases were bulk deleted | | TeamCaseBulkLinkCase | Team cases were bulk linked | | TeamCaseBulkUpdate | Team cases were bulk updated | | TeamCaseButtonCreation | An action (button) was added to a case | | TeamCaseButtonDeletion | A team case button was deleted | | TeamCaseButtonsBulkUpdate | Team case buttons were bulk updated | | TeamCaseButtonUpdate | A team case button was updated | | TeamCaseButtonWebhookTrigger | A team case button webhook was triggered | | TeamCaseCommentCreation | A comment was added to a case | | TeamCaseCommentDeletion | A team case comment was deleted | | TeamCaseCommentUpdate | A comment was updated on a case | | TeamCaseCreation | A case was created | | TeamCaseDeletion | A team case was deleted | | TeamCaseDescriptionUpdate | A team case's description was updated | | TeamCaseFileAttach | A file or comment and file was attached to a case | | TeamCaseFileBlockCreation | A team case file block was created | | TeamCaseFileBlockDeletion | A team case file block was deleted | | TeamCaseFileBlockElementCreation | A team case file block element was created | | TeamCaseFileDeletion | A team case file was deleted | | TeamCaseInputCreation | A team case input was created | | TeamCaseInputDeletion | A team case input was deleted | | TeamCaseInputUpdate | A team case input was updated | | TeamCaseInputValueDeletion | A team case input value was deleted | | TeamCaseInputValueUpsert | A team case input value was upserted | | TeamCaseLinkCase | A team case was linked to another case | | TeamCaseMetadataCreation | Team case metadata was created | | TeamCaseMetadataUpdate | A team case's metadata was updated | | TeamCaseNoteBlockCreation | A team case note block was created | | TeamCaseNoteDeletion | A team case note was deleted | | TeamCaseNoteUpdate | A team case note was updated | | TeamCaseRecordFieldsUpdate | Team case record fields were updated | | TeamCaseRecordResultSetBulkDestruction | Team case record result sets were bulk destroyed | | TeamCaseRecordResultSetCreation | A team case record result set was created | | TeamCaseRecordResultSetDestruction | A team case record result set was destroyed | | TeamCaseRemoveCommentReaction | A reaction was removed from a comment on a case | | TeamCasesExportCreation | A team cases export was created | | TeamCaseSlaCreation | A team case SLA was created | | TeamCaseSlaDeletion | A team case SLA was deleted | | TeamCaseSlaUpdate | A team case SLA was updated | | TeamCasesSavedViewCreation | A saved view was created for a teams cases | | TeamCasesSavedViewDestruction | A saved view was deleted from a teams cases | | TeamCasesSavedViewUpdate | A team cases saved view was updated | | TeamCaseStatusCreation | A team case status was created | | TeamCaseStatusDeletion | A team case status was deleted | | TeamCaseStatusUpdate | A team case status was updated | | TeamCaseSubscriberBulkCreation | Team case subscribers were bulk created | | TeamCaseSubscriberCreation | A subscriber was added to a case | | TeamCaseSubscriberDeletion | A subscriber was removed from a case | | TeamCaseTagsUpdate | A tag was added to or removed from a case | | TeamCaseTemplateCreation | A team case template was created | | TeamCaseTemplateDeletion | A team case template was deleted | | TeamCaseTemplateUpdate | A team case template was updated | | TeamCaseUnlinkCase | A team case was unlinked | | TeamCaseUpdate | A case was assigned, renamed, completed or its description updated | | TeamCaseWebhookUpdate | A case notification webhook was set or updated for the team | | TeamCreation | A team was created | | TeamDestruction | A team was destroyed | | TeamMemberRemoval | A team member was removed | | TeamMembersAddition | A team member was added | | TeamNotificationSettingsUpdate | Team notification settings were updated | | TeamSettingUpdate | A team setting was updated | | TeamStaticExternalIdDestruction | A team static external ID was destroyed | | TeamTunnelMembershipUpdate | A team tunnel membership was updated | | TeamUpdate | A team was updated | | TemplateActionTagUpdate | A template action tag was updated | | TemplateCreation | A template was created | | TemplateDestruction | A template was deleted | | TemplateDuplication | A template was duplicated | | TemplateTestRun | A template test was run | | TemplateUpdate | A template was updated | | TenantAiEnabledToggle | Tenant AI was enabled/disabled | | TenantAiProviderChange | A tenant AI provider was changed | | TenantAiProviderDeletion | A tenant AI provider was deleted | | TenantAiProviderTest | Tenant AI provider was tested | | TenantChangeControlSettingsUpdate | Tenant change control settings were updated | | TenantConfigChange | A tenant's config was changed | | TenantFeatureFlagToggle | A feature flag was enabled/disabled | | TenantLimitsChange | Tenant limits were changed | | TenantPlanUpgradeRequest | A plan upgrade was requested | | TenantSessionTimeoutChange | Tenant session timeout was changed | | TenantSettingsChange | Tenant settings were changed | | TestStoryCreation | Change control was enabled for a story | | TestStoryDeletion | Change control was disabled for a story | | ToolLinkCreation | A tool link was created | | ToolLinkDeletion | A tool link was deleted | | ToolLinkGroupCreation | A tool link group was created | | ToolLinkStsCreation | A tool link STS was created | | ToolLinkTemplatesCreation | Tool link templates were created | | TunnelDestruction | A tunnel was destroyed | | TunnelUpdate | A tunnel was updated | | UpdatePageFromTemplate | A page was updated from a template | | UploadImage | An image was uploaded | | UserCredentialDestruction | A user credential was destroyed | | UserCredentialHttpRequestRun | A user credential HTTP request was run | | UserCredentialMovement | A user credential was moved | | UserCredentialSave | A user credential was saved | | UserDeletion | A user was deleted | | UserEdit | A user was edited | | UserFavoriteIntegrationProductChange | A user's favorite integration product was changed | | UserFavoriteTemplateChange | A user's favorite template was changed | | UserImpersonationDisabled | User impersonation was disabled | | UserImpersonationEnabled | User impersonation was enabled | | UserRecoveryCodesDeletion | User recovery codes were deleted | | UserRecoveryCodesGeneration | User recovery codes were generated | | UserReinvitation | A user's invitation was resent | | UsersInvitation | A user was invited | | UserSessionExpiryChange | User session expiry was changed | | UserTeamRoleChange | A user's team role was changed | | WorkbenchConfigurationCreation | A Workbench preset was created | | WorkbenchConfigurationDeletion | A Workbench preset was permanently deleted | | WorkbenchConfigurationDuplication | A Workbench configuration was duplicated | | WorkbenchConfigurationUpdate | A Workbench preset was updated | | WorkbenchConfiguredProductUpdate | A user enabled/disabled a product or changed its credential in Workbench | | WorkbenchConfiguredStoryUpdate | A story was enabled/disabled in Workbench | | WorkbenchConversationDeletion | A Workbench conversation was permanently deleted | | WorkbenchConversationFork | A new conversation was created, with context up to a fixed point from the original conversation | | WorkbenchConversationRename | A Workbench conversation was renamed | | WorkbenchConversationStart | A new conversation was started in Workbench | | WorkbenchConversationSubmitForEvaluation | A Workbench conversation was submitted for evaluation | | WorkbenchConversationToggleFavorite | Favorite was enabled/disabled for a conversation | | WorkbenchCustomSlackIntegrationCreation | A Workbench integration was created for Slack | | WorkbenchDraftStoryCreation | A draft story was created from a Workbench conversation | | WorkbenchEnableProductTemplates | A user enabled/disabled templates for a product in Workbench | | WorkbenchInstructionChange | Custom instructions for a user were updated | | WorkbenchIntegrationCreation | A Workbench integration was created | | WorkbenchPresetCreation | A Workbench preset was created | | WorkbenchPresetUpdate | A Workbench preset updated | | WorkbenchToolUseCancel | User canceled the use of a tool | | WorkbenchToolUseConfirm | User confirmed the use of a tool | | WorkbenchUserMessageSend | User sent a message to Workbench | | WorkbenchUserMessageStop | User stopped a reply from Workbench | ## Log format Each log contains enriched user information, as well as metadata related to the operation carried out. Extremely sensitive information, for example credential values, are never included. ```json { "created_at": "2022-10-04T19:03:18Z", "id": 123456, "inputs": { "inputs": { "teamId": 1772 } }, "request_ip": "11.22.33.44", "request_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36", "tenant_id": 9, "updated_at": "2022-10-04T19:03:18Z", "user_email": "user@example.com", "user_id": 9, "user_name": "Example User", "operation_name": "StoryCreation" } ``` ### List ## Description Returns a list of audit logs gathered from the Tines tenant. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | before | **Optional** Only include logs created before this timestamp | | after | **Optional** Only include logs created after this timestamp | | user_id | **Optional** Only include logs from a matching user. Use the format `user_id[]=` to select multiple users, i.e. `?user_id[]=1&user_id[]=2`. | | operation_name | **Optional** Only include logs with a specific operation name. Use the format `operation_name[]=` to select multiple operation names, i.e. `?operation_name[]=StoryItemsMovement&operation_name[]=StoryItemsCreation`. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/audit_logs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful response will return a list of logs for every user operation executed on the database along with the associated inputs and the id of the user who triggered the operation. ### Field description | Parameter | Description | | ------------------ | ---------------------------------------------------------------------------- | | created_at | ISO 8601 Timestamp representing creation date and time of log operation. | | operation_name | The name of the operation. | | id | Operation ID | | inputs | JSON Inputs passed to the operation. | | outputs | JSON Outputs generated by the operation. | | request_ip | The IP Address the operation was triggered from | | request_user_agent | The user agent that the operation was triggered with | | tenant_id | The ID of the tenant the operation was triggered on. | | updated_at | ISO 8601 Timestamp representing last updated date and time of log operation. | | user_email | The email of the user who triggered the operation. | | user_id | The ID of the user who triggered the operation. | | user_name | The name of the user who triggered the operation. | | story_id | ID of the story that the operation was run on (null if there is no story). | ### Sample response ```json { "audit_logs": [ { "created_at": "2022-06-24T08:35:21Z", "operation_name": "StoryItemsMovement", "id": 19990840, "inputs": { "storyId": 3480, "inputs": { "actionIds": [21246], "diagramNoteIds": [], "delta": { "x": 61, "y": 0 } } }, "outputs": {}, "request_ip": "127.0.0.1", "request_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36", "tenant_id": 1, "updated_at": "2022-06-24T08:35:21Z", "user_email": "name@example.com", "user_id": 622, "user_name": "Name Person", "story_id": 3480 } ], "meta": { "current_page": "https://hq.tines.io/api/v1/audit_logs?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ## Credentials ### Create: AWS type ## Description Use a HTTP POST request to create a [AWS](/docs/credentials/aws) credential. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`AWS`) | | team_id | ID of Tines Team where the credential will be located. | | aws_authentication_type | The authentication method with AWS, key-based-access or role-based-access(`KEY`, `ROLE`, `INSTANCE_PROFILE`) | | aws_access_key | The `access key` from your [AWS Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | | aws_secret_key | The `access secret` from your [AWS Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | | aws_assumed_role_arn | **Required for role-based-access** The ARN of the role you wish to assume, e.g.: `arn:aws:iam::123456789012:role/write-access-role` | | use_static_external_id | **Optional** Boolean to indicate whether the credential should use a [team-scoped static external ID](/docs/credentials/aws/#static-external-ids) | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string) | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "aws credential", "mode": "AWS", "team_id": 2, "aws_authentication_type": "ROLE", "aws_access_key": "v_access_key", "aws_secret_key": "v_secret_key", "aws_assumed_role_arn": "v_role_arn" }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | aws_assumed_role_external_id | External ID generated for the remote role in your AWS account. | | use_static_external_id | A boolean value stating if the credential uses a team scoped static external ID. | | aws_authentication_type | The authentication method with AWS, key-based-access or role-based-access(`KEY`, `ROLE`, `INSTANCE_PROFILE`) | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata relevant to the credential | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "AWS", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "aws_assumed_role_external_id": "1e52dbcf-3621-4969-9bf6-3fd2699db84b", "use_static_external_id": false, "aws_authentication_type": "ROLE", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Create: HTTP Request type ## Description Use a HTTP POST request to create a [HTTP Request](/docs/credentials/http-request) credential. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`HTTP_REQUEST_AGENT`) | | team_id | ID of Tines Team where the credential will be located. | | http_request_options | JSON object representing the Agents::HTTPRequestAgent Options | | http_request_location_of_token | Location of token from response | | http_request_secret | **Optional** Secret value to save in an http request. This can be referenced as `secret` in the HTTP request options builder. | | http_request_ttl | **Optional** Time to live (TTL) in seconds. Not sending this value during an update/PUT operation will update it to null. | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request The `<>` maps to the value provided to the `http_request_secret` key as described above. ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "http credential", "mode": "HTTP_REQUEST_AGENT", "team_id": 2, "http_request_options": { "url": "http://www.example.com", "content_type": "application_json", "method": "post", "payload": { "key": "value", "secret": "I can reference the \\<> as needed in the payload." }, "headers": {} }, "http_request_location_of_token": "\\=credential_name.body.token", "http_request_secret": "secret_value", "allowed_hosts": ["exampledomain.com", "seconddomain.com"] }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata relevant to the credential | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "HTTP_REQUEST_AGENT", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Create: JWT type ## Description Use a HTTP POST request to create a [JWT tokens](/docs/credentials/jwt) credential. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`JWT`) | | jwt_algorithm | The algorithm to be used when computing the JWT | | jwt_payload | The payload to be included in the JWT | | jwt_auto_generate_time_claims | Auto generate ‘iat’ & ‘exp’ claims | | jwt_private_key | The private key to be used to sign the JWT | | team_id | ID of Tines Team where the credential will be located. | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "jwt credential", "mode": "JWT", "team_id": 2, "jwt_algorithm": "RS256", "jwt_payload": { "iss": "", "sub": "", "scope": "", "aud": "" }, "jwt_auto_generate_time_claims": true, "jwt_private_key": "" }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata relevant to the credential | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "JWT", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Create: MTLS type ## Description Use a HTTP POST request to create a [Mutual TLS](/docs/credentials/mtls) credential. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`MTLS`) | | team_id | ID of Tines Team where the credential will be located. | | mtls_client_certificate | The certificate file issued by the CA for this client | | mtls_client_private_key | The private key file for the client certificate | | mtls_root_certificate | The root certificate file for the certificate authority (CA) responsible for signatures | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "mtls credential", "mode": "MTLS", "team_id": 2, "mtls_client_certificate": "", "mtls_client_private_key": "", "mtls_root_certificate": "" }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata relevant to the credential | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "MTLS", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Create: Multi Request type ## Description Use a HTTP POST request to create a [Multi Request](/docs/credentials/multi-request) credential. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`MULTI_REQUEST`) | | team_id | ID of Tines Team where the credential will be located. | | http_request_location_of_token | Location of token from response | | credential_requests | Details of the HTTP requests that are made to fetch the credential value. This should be an array of two objects, each with a required `options` key containing the JSON object representing the Agents::HTTPRequestAgent and an `http_request_secret` key, used to pass secrets to the options. The order of the objects in the array passed to `credential_requests` determines the order in which the requests will run. | | http_request_ttl | **Optional** Time to live (TTL) in seconds. Not sending this value during an update/PUT operation will update it to null. | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "multi request credential", "mode": "MULTI_REQUEST", "team_id": "=META.team.id", "http_request_location_of_token": "\\=credential_name.body.token", "credential_requests": [ { "options": { "url": "http://www.example.com", "content_type": "application_json", "method": "post", "payload": { "key": "value", "secret": "I can reference the \\<> as needed in the payload." }, "headers": {} }, "http_request_secret": "secret_value" }, { "options": { "url": "http://www.example.com", "content_type": "application_json", "method": "post", "payload": { "key": "value", "secret": "I can reference the \\<> or the \\<> as needed in the payload." }, "headers": {} }, "http_request_secret": "secret_value" } ] }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata relevant to the credential | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "MULTI_REQUEST", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Create: OAuth type ## Description Use a HTTP POST request to create a [OAuth2.0](/docs/credentials/oauth) credential. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`OAUTH`). | | oauth_url | Your app oauth url. Required for grant type `authorization_code`. | | oauth_token_url | Your app oauth token url | | oauth_client_id | The client ID for your app | | oauth_client_secret | The client secret for your app | | oauth_scope | Enter one or more scope values indicating which parts of the user’s account you wish to access. | | oauth_grant_type | Tines supports `client_credentials` and `authorization_code` grants. | | team_id | ID of Tines Team where the credential will be located. | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`). default: `TEAM` | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | oauthPkceCodeChallengeMethod | **Optional** PKCE challenge method (`S256`, `plain`). default: `NULL` (None). | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "oauth credential", "mode": "OAUTH", "team_id": 2, "oauth_url": "https://example.com/auth", "oauth_token_url": "https://example.com/token", "oauth_client_id": "foo", "oauth_client_secret": "bar", "oauth_scope": "sync", "oauth_grant_type": "authorization_code" }' ``` ## Response A successful request will return a JSON object containing a `redirect_url` to complete the registration process and a description of the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests | | metadata | Key/value metadata relevant to the credential | | redirect_url | Redirect URL of the created credential. | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "redirect_url": "", "id": 1, "name": "tines_api_credential", "mode": "OAUTH", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Create: Text type ## Description Use a HTTP POST request to create a [Text](/docs/credentials/text) credential. Please note, for test credentials that will be used in TEST mode of change control, the optional value 'live_credential_id' must be provided. In this scenario, the other optional values (i.e. credential description, read access, team ID, folder ID) will default to the specified live credential ID. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT`) | | value | Value of the credential. | | team_id | ID of Tines Team where the credential will be located. | | folder_id | **Optional** ID of folder to which the credential will be located | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | metadata | **Optional** Key/value metadata relevant to the credential that can be referenced via the INFO path. | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | live_credential_id | **Optional** ID of the live credential | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample request ```bash curl -X POST \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "text credential", "value": "bar", "mode": "TEXT", "team_id": 2 }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata relevant to the credential | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "TEXT", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Get ## Description Retrieve a credential. ## Request HTTP Method: **GET** | Parameter | Description | | ------------- | ------------------------------------- | | credential_id | The ID of the credential to retrieve. | ```bash curl -X GET \ https:///api/v1/user_credentials/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the selected credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name. | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | aws_assumed_role_external_id | External ID for AWS assumed role, if exists. | | use_static_external_id | A boolean value stating if the credential uses a team-scoped static external ID, applicable to AWS credentials | | aws_authentication_type | The authentication method with AWS, key-based-access or role-based-access(`KEY`, `ROLE`, `INSTANCE_PROFILE`), if exists. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata for use in HTTP requests alongside the credential value. | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_github_credential", "mode": "TEXT", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_github_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "aws_assumed_role_external_id": null, "aws_authentication_type": null, "use_static_external_id": false, "allowed_hosts": [], "metadata": { "account_domain": "https://example.com" }, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### Update ## Description Use a HTTP PUT request to update a [credential](/docs/credentials). ## Request HTTP Method: **PUT** | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | name | **Optional** Name of the credential. | | folder_id | **Optional** The ID of the folder to move the credential to, or an empty value to indicate the root folder. Note that this folder must exist within the team identified by `team_id`, or the credential's current team if `team_id` isn't specified. | | read_access | **Optional** Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this credential can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the credential. default: `""` (empty string). | | metadata | **Optional** Key/value metadata for use in HTTP requests alongside the credential value | | allowed_hosts | **Optional** Array of domains where this credential can only be used in HTTP requests. Domain matching supports wildcards. | | test_credential_enabled | **Optional** A boolean value stating if the credential is enabled for using a test credential | | is_test | **Optional** Boolean value stating if the test credential should be updated. `test_credential_enabled` must be set to `TRUE` and a test credential must exist for the update to succeed. | | expires_at | **Optional** ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | **Optional** A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | **Optional** List of user IDs that will be sent credential notifications (e.g. expiry notifications) | #### TEXT Options | Parameter | Description | | --------- | ------------------------ | | value | Value of the credential. | #### OAUTH Options | Parameter | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------- | | oauth_url | Your app oauth url | | oauth_token_url | Your app oauth token url | | oauth_client_id | The client ID for your app | | oauth_client_secret | The client secret for your app | | oauth_scope | Enter one or more scope values indicating which parts of the user’s account you wish to access | | oauth_grant_type | Tines supports `client_credentials` and `authorization_code` grants. | | oauthPkceCodeChallengeMethod | PKCE challenge method (`S256`, `plain`). default: `NULL` (None). | #### MTLS Options | Parameter | Description | | ----------------------- | --------------------------------------------------------------------------------------- | | mtls_client_certificate | The certificate file issued by the CA for this client | | mtls_client_private_key | The private key file for the client certificate | | mtls_root_certificate | The root certificate file for the certificate authority (CA) responsible for signatures | #### JWT Options | Parameter | Description | | ----------------------------- | ----------------------------------------------- | | jwt_algorithm | The algorithm to be used when computing the JWT | | jwt_payload | The payload to be included in the JWT | | jwt_auto_generate_time_claims | Auto generate ‘iat’ & ‘exp’ claims | | jwt_private_key | The private key to be used to sign the JWT | #### HTTP_REQUEST_AGENT Options | Parameter | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | http_request_options | JSON string representing the Agents::HTTPRequestAgent Options (required) | | http_request_location_of_token | Location of token from response (required) | | http_request_secret | Secret value to save in an http request. This can be referenced as `secret` in the HTTP request options builder. | | http_request_ttl | Time to live (TTL) in seconds. Not sending this value during an update/PUT operation will update it to null. | #### MULTI_REQUEST Options | Parameter | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | | http_request_location_of_token | Location of token from response (required) | | credential_requests | List of requests to run to fetch the credential values (required). | | http_request_ttl | Time to live (TTL) in seconds. Not sending this value during an update/PUT operation will update it to null. | #### AWS Options | Parameter | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | aws_authentication_type | The authentication method with AWS, key-based-access or role-based-access(`KEY`, `ROLE`, `INSTANCE_PROFILE`) | | aws_access_key | The `access key` from your [AWS Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | | aws_secret_key | The `access secret` from your [AWS Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | | aws_assumed_role_arn | **Required for role-based-access** The ARN of the role you wish to assume, e.g.: `arn:aws:iam::123456789012:role/write-access-role` | ### Sample request ```bash curl -X PUT \ https:///api/v1/user_credentials/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated credential name", "value": "Updated secret value", "mode": "TEXT", "metadata": { "account_domain": "https://updatedmetadataexample.com" } }' ``` ## Response A successful request will return a JSON object describing the created credential. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata for use in HTTP requests alongside the credential value. | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "id": 1, "name": "tines_api_credential", "mode": "TEXT", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_api_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "allowed_hosts": [], "metadata": { "account_domain": "https://example.com" }, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ``` ### List ## Description Retrieve a list of credentials. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | team_id | **Optional** List actions for the given team | | folder_id | **Optional** List actions for the given folder | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | filter | **Optional** Filter by one of: `UNUSED_IN_ACTIONS`, `UNRESTRICTED`, `RESTRICTED` | ```bash curl -X GET \ https:///api/v1/user_credentials \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing credentials in the Tines tenant. ### Field description | Parameter | Description | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | credential ID. | | name | Name of the credential. | | mode | Describes the type of credential (`TEXT, JWT, OAUTH, AWS, MTLS, HTTP_REQUEST_AGENT, MULTI_REQUEST`). | | team_id | ID of team to which the credential belongs. | | folder_id | ID of folder to which the credential belongs. | | read_access | Control where this credential can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this credential can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | description | Description of the credential. | | slug | An underscored representation of the credential name. | | created_at | ISO 8601 Timestamp representing date and time the credential was created. | | updated_at | ISO 8601 Timestamp representing date and time the credential was last updated. | | aws_assumed_role_external_id | External ID for AWS assumed role, if exists. | | aws_authentication_type | The authentication method with AWS, key-based-access or role-based-access(`KEY`, `ROLE`, `INSTANCE_PROFILE`), if exists. | | allowed_hosts | Array of domains where this credential can only be used in HTTP requests. | | metadata | Key/value metadata for use in HTTP requests alongside the credential value. | | restriction_type | The type of restriction applied to the use of the credential (`RESTRICTED`,`RESTRICTED_TO_CREDENTIALS` ,`UNRESTRICTED` ) | | test_credential_enabled | A boolean value stating if the credential is enabled for using a test credential | | test_credential | Data specific to the test credential (`created_at` and `updated_at`) | | owner | An object representing the user who owns this credential. By default, the owner is the user who created the credential. | | expires_at | ISO 8601 Timestamp representing date and time the credential will expire. Default: `null`. See: [Credential expiry](https://www.tines.com/docs/credentials/credential-configuration/expiry) | | expiry_notifications_enabled | A boolean value stating whether or not expiry notifications are enabled. Default: `false`. See: [Credential expiry email reminders](https://www.tines.com/docs/credentials/credential-configuration/expiry/#email-reminders) | | credential_notification_recipient_user_ids | List of user IDs that will be sent credential notifications (e.g. expiry notifications) | ### Sample response ```json { "user_credentials": [ { "id": 1, "name": "tines_github_credential", "mode": "TEXT", "team_id": 2, "folder_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_github_credential", "created_at": "2021-03-26T12:34:16.540Z", "updated_at": "2021-03-26T12:34:16.540Z", "description": "", "aws_assumed_role_external_id": null, "aws_authentication_type": null, "allowed_hosts": [], "metadata": {}, "restriction_type": "UNRESTRICTED", "test_credential_enabled": false, "owner": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io" } } ], "meta": { "current_page": "https:///api/v1/user_credentials?per_page=1&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 1, "pages": 1, "count": 1 } } ``` ### Delete ## Description Delete a credential. ## Request HTTP Method: **DELETE** | Parameter | Description | | ------------- | ----------------------------------- | | credential_id | The ID of the credential to delete. | ```bash curl -X DELETE \ https:///api/v1/user_credentials/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON object with a `null` body and a `204` status code. ## Folders ### Create a Folder ## Description Create a folder in Tines. ## Request HTTP Method: **POST** | Query Parameter | Description | | ---------------- | ---------------------------------------------------------------------------- | | name | The folder name. | | content_type | The type of content stored in this folder `CREDENTIAL` `RESOURCE` or `STORY` | | team_id | ID of team to which the folder should be created. | | parent_folder_id | **Optional** ID of the parent folder. Default: `null` (root level). | ### Sample request ```bash curl -X POST \ https:///api/v1/folders/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "Folder name", "content_type": "CREDENTIAL", "team_id": 1, "parent_folder_id": 5 }' ``` ## Response A successful request will return a JSON object describing the created folder ### Field description | Parameter | Description | | ---------------- | -------------------------------------------------------- | | id | The folder ID. | | name | The folder name. | | team_id | ID of team to which the folder belongs. | | content_type | The type of content stored in this folder | | size | The number of items in this folder | | parent_folder_id | ID of the parent folder, or `null` if at the root level. | ### Sample response ```json { "id": 1, "name": "Folder name", "content_type": "CREDENTIAL", "team_id": 1, "size": 0, "parent_folder_id": 5 } ``` ### Get a Folder ## Description Retrieve a single folder. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------- | | folder_id | The ID of the folder to retrieve. | ```bash curl -X GET \ https:///api/v1/folders/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified folder. ### Field description | Parameter | Description | | ---------------- | -------------------------------------------------------- | | id | The folder ID. | | name | The folder name. | | team_id | ID of team to which the folder belongs. | | content_type | The type of content stored in this folder | | size | The number of items in this folder | | parent_folder_id | ID of the parent folder, or `null` if at the root level. | ### Sample response ```json { "id": 1, "name": "Folder name", "content_type": "CREDENTIAL", "team_id": 1, "size": 0, "parent_folder_id": null } ``` ### Update a Folder ## Description Update a folder. ## Request HTTP Method: **PUT** | Query Parameter | Description | | ---------------- | -------------------------------------------------------------------------- | | name | The folder name. | | parent_folder_id | **Optional** ID of the parent folder. Set to `null` to move to root level. | | Path Parameter | Description | | -------------- | ---------------- | | folder_id | ID of the folder | ### Sample request ```bash curl -X PUT \ https:///api/v1/folders/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "New folder name", "parent_folder_id": 5 }' ``` ## Response A successful request will return a JSON object describing the updated folder ### Field description | Parameter | Description | | ---------------- | -------------------------------------------------------- | | id | The folder ID. | | name | The folder name. | | team_id | ID of team to which the folder belongs. | | content_type | The type of content stored in this folder | | size | The number of items in this folder | | parent_folder_id | ID of the parent folder, or `null` if at the root level. | ### Sample response ```json { "id": 1, "name": "New folder name", "content_type": "CREDENTIAL", "team_id": 1, "size": 0, "parent_folder_id": 5 } ``` ### List Folders ## Description Retrieve a list of folders. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | team_id | **Optional** ID of team to which the folders belong. | | content_type | **Optional** The type of content stored in the folders. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/folders \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing folders in the Tines tenant. ### Field description | Parameter | Description | | ---------------- | -------------------------------------------------------- | | id | The folder ID. | | name | The folder name. | | team_id | ID of team to which the folder belongs. | | content_type | The type of content stored in the folder | | size | The number of items in this folder | | parent_folder_id | ID of the parent folder, or `null` if at the root level. | ### Sample response ```json { "folders": [ { "id": 1, "name": "Credential folder", "content_type": "CREDENTIAL", "team_id": 1, "size": 1, "parent_folder_id": null }, { "id": 2, "name": "Resource folder", "content_type": "RESOURCE", "team_id": 1, "size": 1, "parent_folder_id": null }, { "id": 3, "name": "Story folder", "content_type": "STORY", "team_id": 1, "size": 5, "parent_folder_id": 1 } ], "meta": { "current_page": "https:///api/v1/folders?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 } } ``` ### Delete Folder ## Description Delete a folder. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ------------------------------- | | folder_id | The ID of the folder to delete. | ```bash curl -X DELETE \ https:///api/v1/folders/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ## Resources ### Create: file type ## Description Create a file resource with Base64-encoded content. ## File value object The `value` parameter must be a JSON object with: | Field | Required | Description | | -------- | -------- | ----------------------------------- | | name | Yes | File name (e.g., "document.pdf") | | contents | Yes | Base64-encoded file contents | | type | No | MIME type (e.g., "application/pdf") | ## Sample request ```bash curl -X POST \ https:///api/v1/global_resources \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "my_file_resource", "team_id": 2, "value": { "name": "example.txt", "contents": "SGVsbG8gV29ybGQh", "type": "text/plain" } }' ``` For all parameters and response fields, see [Create: text type](/api/resources/create-text). ### Create: JSON type ## Description Create a JSON resource (object or array). ## Sample request ```bash curl -X POST \ https:///api/v1/global_resources \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "a json resource", "value": {"fizz":"buzz"}, "team_id": 2, "folder_id": 1 }' ``` For all parameters and response fields, see [Create: text type](/api/resources/create-text). ### Create: text type ## Description Create a text resource in Tines. Please note, for test resources that will be used in TEST mode of change control, the optional value 'Live Resource ID' must be provided. In this scenario, the other optional values (i.e. resource description, read access, team ID, folder ID) will default to the specified live resource ID. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of the resource. | | value | Contents of the resource. When a non-JSON string is passed in, it will be parsed as regular text. | | team_id | ID of Tines Team where the resource will be located. | | folder_id | **Optional** ID of folder to which the resource will be located | | read_access | **Optional** Control where this resource can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this resource can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the resource. default: `""` (empty string) | | live_resource_id | **Optional** The id of live resource that corresponds to the new test value | | include_referencing_action_ids | **Optional** Defaults to `true`, when set to `false` we will exclude `referencing_action_ids` from the response | | typed_value | **Optional** Defaults to `false`. When set to `true`, returns properly typed values (boolean, number, array, object) instead of strings | ### Sample request ```bash curl -X POST \ https:///api/v1/global_resources \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "foo", "value": "bar" }' ``` ## Response A successful request will return a JSON object describing the created resource. Test resource data is contained within the live resource. ### Field description | Parameter | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Resource ID. | | name | Name of the resource. | | value | Value of the resource. By default, returns a string representation. Use `typed_value=true` to get properly typed values (boolean, number, array, object). | | team_id | ID of team to which the resource belongs. | | folder_id | ID of folder to which the resource belongs. | | user_id | ID of user associated with the resource. | | read_access | Control where this resource can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this resource can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | slug | An underscored representation of the resource name | | created_at | ISO 8601 Timestamp representing date and time the resource was created. | | updated_at | ISO 8601 Timestamp representing date and time the resource was last updated. | | description | Description of the resource. | | test_resource_enabled | A boolean value stating if the resource is enabled for using a test resource. | | test_resource | JSON block of the test resource. | | referencing_action_ids | IDs of action that are referencing the Resource. | ### Sample response ```json { "id": 9, "name": "foo", "value": "bar", "team_id": 2, "folder_id": 1, "user_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "foo", "created_at": "2020-02-05T20:40:32.313Z", "updated_at": "2020-02-05T20:55:18.239Z", "description": "", "test_resource_enabled": false } ``` ### Get ## Description Retrieve a resource. ## Request HTTP Method: **GET** | Parameter | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | resource_id | The ID of the live resource to retrieve. | | include_referencing_action_ids | **Optional** Defaults to `true`, when set to `false` we will exclude `referencing_action_ids` from the response | | typed_value | **Optional** Defaults to `false`. When set to `true`, returns properly typed values (boolean, number, array, object) instead of strings | ```bash curl -X GET \ https:///api/v1/global_resources/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Example with typed_value To retrieve a resource with properly typed values (e.g., `true` as a boolean instead of `"true"` as a string): ```bash curl -X GET \ https:///api/v1/global_resources/<>?typed_value=true \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the selected resource. ### Field description | Parameter | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Resource ID. | | name | Name of the resource. | | value | Value of the resource. By default, returns a string representation. Use `typed_value=true` to get properly typed values. For file resources, contains `name`, `contents`, and `type` fields. | | team_id | ID of team to which the resource belongs. | | folder_id | ID of folder to which the resource belongs. | | user_id | ID of user associated with the resource. | | read_access | Control where this resource can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this resource can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | slug | An underscored representation of the resource name | | created_at | ISO 8601 Timestamp representing date and time the resource was created. | | updated_at | ISO 8601 Timestamp representing date and time the resource was last updated. | | description | Description of the resource. | | test_resource_enabled | A boolean value stating if the resource is enabled for using a test resource. | | test_resource | JSON block of the test resource. | | referencing_action_ids | IDs of action that are referencing the Resource. | ### Sample response **Default response (typed_value=false or omitted):** ```json { "id": 1, "name": "tines_jira_url", "value": "tinesio.atlassian.net", "team_id": 2, "folder_id": 1, "user_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_jira_url", "created_at": "2019-12-12T21:34:16.540Z", "updated_at": "2019-12-12T21:34:16.540Z", "description": "", "test_resource_enabled": false, "referencing_action_ids": [431] } ``` **Response with typed_value=true:** When `typed_value=true` is specified, values are returned with their proper types: ```json { "id": 2, "name": "enable_feature", "value": true, "team_id": 2, "folder_id": 1, "user_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "enable_feature", "created_at": "2019-12-12T21:34:16.540Z", "updated_at": "2019-12-12T21:34:16.540Z", "description": "", "test_resource_enabled": false, "referencing_action_ids": [432] } ``` Note: In the example above, `value` is a boolean `true` rather than the string `"true"`. This applies to all value types: - Booleans: `true` / `false` (not `"true"` / `"false"`) - Numbers: `42` (not `"42"`) - Arrays: `["a", "b"]` (not `"[\"a\",\"b\"]"`) - Objects: `{"key": "value"}` (not `"{\"key\":\"value\"}"`) - Strings: remain as strings ### Update ## Description Use a HTTP PUT request to update a resource. If the resource has a test value this can be modified by using the is_test parameter. ## Request HTTP Method: **PUT** | Parameter | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | resource_id | The ID of the live resource. | | value | Contents of the resource. For file resources, pass a JSON object with file data (see below). | | name | **Optional** Name of the resource. | | folder_id | **Optional** The ID of the folder to move the resource to, or an empty value to indicate the root folder. Note that this folder must exist within the team identified by `team_id`, or the resource's current team if `team_id` isn't specified. | | read_access | **Optional** Control where this resource can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default: `TEAM`. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this resource can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. default: `[]` (empty array). | | description | **Optional** Description of the resource. default: `""` (empty string). | | test_resource_enabled | **Optional** Boolean value stating if the resource is enabled for using a test. resource | | is_test | **Optional** Boolean value stating if the test resource should be updated. `test_resource_enabled` must be set to `TRUE` and a test resource must exist for the update to succeed. | | include_referencing_action_ids | **Optional** Defaults to `true`, when set to `false` we will exclude `referencing_action_ids` from the response | | typed_value | **Optional** Defaults to `false`. When set to `true`, returns properly typed values (boolean, number, array, object) instead of strings | ### File value object | Field | Required | Description | | -------- | -------- | ----------------------------------- | | name | Yes | File name (e.g., "document.pdf") | | contents | Yes | Base64-encoded file contents | | type | No | MIME type (e.g., "application/pdf") | ### Sample request (text resource) ```bash curl -X PUT \ https:///api/v1/global_resources/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value":"updated resource value" }' ``` ### Sample request (file resource) ```bash curl -X PUT \ https:///api/v1/global_resources/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": { "name": "updated_document.pdf", "contents": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovQ3...", "type": "application/pdf" } }' ``` ## Response A successful request will return a JSON object describing the updated resource. Test resource data is contained within the live resource. ### Field description | Parameter | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Resource ID. | | name | Name of the resource. | | value | Value of the resource. By default, returns a string representation. Use `typed_value=true` to get properly typed values (boolean, number, array, object). | | team_id | ID of team to which the resource belongs. | | folder_id | ID of folder to which the resource belongs. | | user_id | ID of user associated with the resource. | | read_access | Control where this resource can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this resource can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | slug | An underscored representation of the resource name | | created_at | ISO 8601 Timestamp representing date and time the resource was created. | | updated_at | ISO 8601 Timestamp representing date and time the resource was last updated. | | description | Description of the resource. | | test_resource_enabled | A boolean value stating if the resource is enabled for using a test resource. | | test_resource | JSON block of the test resource. | | referencing_action_ids | IDs of action that are referencing the Resource. | ### Sample response ```json { "id": 9, "name": "an array resource", "value": "updated resource value", "team_id": 1, "folder_id": 1, "user_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "an_array_resource", "created_at": "2020-02-05T20:40:32.313Z", "updated_at": "2020-02-05T20:55:18.239Z", "description": "", "test_resource_enabled": false } ``` ### List ## Description Retrieve a list of resources. ## Request HTTP Method: **GET** | Query Parameter | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | team_id | **Optional** Return resources belonging to this team. | | folder_id | **Optional** Return resources in this folder. | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | filter | **Optional** Filter: `UNUSED_IN_ACTIONS` | | include_referencing_action_ids | **Optional** Defaults to `true`, when set to `false` we will exclude `referencing_action_ids` from the response | | typed_value | **Optional** Defaults to `false`. When set to `true`, returns properly typed values (boolean, number, array, object) instead of strings | ```bash curl -X GET \ https:///api/v1/global_resources \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing resources in the Tines tenant.\ Results are paginated by default to 20 results returned per page. ### Field description | Parameter | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Resource ID. | | name | Name of the resource. | | value | Value of the resource. By default, returns a string representation. Use `typed_value=true` to get properly typed values (boolean, number, array, object). | | team_id | ID of team to which the resource belongs. | | folder_id | ID of folder to which the resource belongs. | | user_id | ID of user associated with the resource. | | read_access | Control where this resource can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this resource can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | slug | An underscored representation of the resource name | | created_at | ISO 8601 Timestamp representing date and time the resource was created. | | updated_at | ISO 8601 Timestamp representing date and time the resource was last updated. | | description | Description of the resource. | | test_resource_enabled | A boolean value stating if the resource is enabled for using a test resource. | | test_resource | JSON block of the test resource. | | referencing_action_ids | IDs of action that are referencing the Resource. | ### Sample response ```json { "global_resources": [ { "id": 1, "name": "tines_jira_url", "value": "tinesio.atlassian.net", "team_id": 2, "folder_id": 1, "user_id": 1, "read_access": "TEAM", "shared_team_slugs": [], "slug": "tines_jira_url", "created_at": "2019-12-12T21:34:16.540Z", "updated_at": "2019-12-12T21:34:16.540Z", "description": "", "test_resource_enabled": true, "test_resource": { "value": "test resource", "created_at": "2019-12-12T22:34:16.540Z", "updated_at": "2019-12-12T22:34:16.540Z" }, "referencing_action_ids": [431] } ], "meta": { "current_page": "https:///api/v1/global_resources?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Remove element ## Description Remove a top level element from an array or key from an object in a resource. The request returns the removed item. If the resource has a test value this can be modified by using the is_test parameter. ## Request HTTP Method: **POST** | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | resource_id | The ID of the live resource. | | key | The object key to remove if removing from an object. | | index | The index of the element to remove if removing from an array (with indexes starting at 0). If omitted the last element of the array will be removed | | if_value | **Optional** When provided, the operation only proceeds if the current value at the specified key (for objects) or index (for arrays) matches this value. If the value does not match, a 422 error is returned with the current value included in the response. Supports any JSON value (string, number, boolean, object, array). A `null` value is treated the same as omitting the parameter (unconditional operation). | | is_test | **Optional** Boolean value stating if the test resource should be used | ### Sample request Sample request for an array element ```bash curl -X POST \ https:///api/v1/global_resources/<>/remove \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "index":"0" }' ``` Sample request for an object key ```bash curl -X POST \ https:///api/v1/global_resources/<>/remove \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "key":"foo" }' ``` Sample request for conditional removal (only removes if current value matches) ```bash curl -X POST \ https:///api/v1/global_resources/<>/remove \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "key": "locked_by", "if_value": "run-123" }' ``` ## Response A successful request will return the removed item from the resource in string format. ### Sample response ```json "foo bar" ``` ### Delete ## Description Delete a resource. ## Request HTTP Method: **DELETE** | Parameter | Description | | ----------- | -------------------------------------- | | resource_id | The ID of the live resource to delete. | ```bash curl -X DELETE \ https:///api/v1/global_resources/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Append element ## Description Append a string or an array to a resource. If the resource has a test value this can be modified by using the is_test parameter. ## Request HTTP Method: **POST** | Parameter | Description | | ----------- | ---------------------------------------------------------------------- | | resource_id | The ID of the live resource. | | value | The string or an array to append to the resource. | | is_test | **Optional** Boolean value stating if the test resource should be used | ### Sample request ```bash curl -X POST \ https:///api/v1/global_resources/<>/append \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value":"[1,2,3,4,5]" }' ``` ## Response A successful request will return the updated resource value ### Sample response ```json [1, 2, 3, 4, 5] ``` ### Replace element ## Description Replace a top level element from an array or key from an object in a resource. The request returns the updated resource. If the resource has a test value this can be modified by using the is_test parameter. ## Request HTTP Method: **POST** | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | resource_id | The ID of the live resource. | | key | The object key to replace if replacing from an object. | | index | The index of the element to replace if replacing from an array (with indexes starting at 0). | | value | The new value to replace the existing element with | | if_value | **Optional** When provided, the operation only proceeds if the current value at the specified key (for objects) or index (for arrays) matches this value. If the value does not match, a 422 error is returned with the current value included in the response. Supports any JSON value (string, number, boolean, object, array). A `null` value is treated the same as omitting the parameter (unconditional operation). | | is_test | **Optional** Boolean value stating if the test resource should be used | ### Sample request Sample request for an array element ```bash curl -X POST \ https:///api/v1/global_resources/<>/replace \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "index": "0", "value": "new-value" }' ``` Sample request for an object key ```bash curl -X POST \ https:///api/v1/global_resources/<>/replace \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "key": "foo", "value": "new-value" }' ``` Sample request for conditional replacement (compare-and-swap) ```bash curl -X POST \ https:///api/v1/global_resources/<>/replace \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "key": "count", "value": 6, "if_value": 5 }' ``` ## Examples ### Replacing an element in an array Given a resource with value: ```json ["alice", "bob", "charlie"] ``` Sending `{ "index": "1", "value": "eve" }` updates the resource to: ```json ["alice", "eve", "charlie"] ``` ### Replacing a key in an object Given a resource with value: ```json { "city": "Cork", "country": "Ireland" } ``` Sending `{ "key": "city", "value": "Galway" }` updates the resource to: ```json { "city": "Galway", "country": "Ireland" } ``` ### Conditional replacement (compare-and-swap) Given a resource with value: ```json { "count": 5 } ``` Sending `{ "key": "count", "value": 6, "if_value": 5 }` updates the resource to: ```json { "count": 6 } ``` If `count` were any other value, the request would return a 422 error with the current value and the resource would remain unchanged. ## Response A successful request will return the updated resource value. ### Sample response ```json { "city": "Galway", "country": "Ireland" } ``` ### Lock/unlock ## Description Lock or unlock a resource. Locking a resource prevents its value from being modified. Requires `RESOURCE_MANAGE` permission. Unlocking via the API is **permanent** — the resource remains unlocked until explicitly locked again. This differs from the Tines UI, which offers a temporary unlock that automatically re-locks the resource after a single edit. Locking or unlocking a resource also applies to its test resource. A test resource cannot be locked or unlocked independently from its live resource. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ------------------------------------------------------- | | id | The ID of the resource. | | locked | Boolean. `true` to lock the resource, `false` to unlock | ### Sample request ```bash curl -X PUT \ https:///api/v1/global_resources/<>/locked \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"locked": true}' ``` ## Response A successful request will return a JSON object with the resource's `id` and `locked` status. ### Sample response ```json { "id": 9, "locked": true } ``` ## Stories ### Create ## Description Create a story in Tines. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | ID of team to which the story should be added. | | name | **Optional** The story name. | | description | **Optional** A user-defined description of the story. | | keep_events_for | **Optional** Event retention period in seconds:
1 hour: `3600`
6 hours: `21600`
1 day: `86400`
3 days: `259200`
7 days: `604800`
14 days: `1209600 `
30 days: `2592000`
60 days: `5184000`
90 days: `7776000`
180 days: `15552000`
365 days: `31536000` | | folder_id | **Optional** ID of folder to which the story should be added. | | tags | **Optional** An array of Strings used to create tags to classify the story. | | disabled | **Optional** Boolean flag indicating whether the story is disabled (default: `false`) | | priority | **Optional** Boolean flag indicating if this is a high priority story (default: `false`). | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Simple story", "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "team_id": 1, "folder_id": 1 }' ``` ## Response A successful request will return a JSON object describing the created story ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | ### Sample response ```json { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ] } ``` ### Get ## Description Retrieve a single story. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------------------- | | story_id | The ID of the story to retrieve. | | Query Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | story_mode | **Optional** The mode (`TEST` or `LIVE`) of the story to retrieve. | | draft_id | **Optional** The ID of the draft to retrieve. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | include_live_activity | **Optional** When set to `true`, includes live activity metrics like `pending_action_runs_count`, `concurrent_runs_count`, and `tokens_used_percentage`. Defaults to `false`. | ```bash curl -X GET \ https:///api/v1/stories/<>?include_live_activity=true \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified story. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | | api_enabled | Boolean flag indicating if Webhook API is enabled. | | api_entry_actions | Array of entry action ID for API enabled story. | | api_exit_actions | Array of exit action IDs for API enabled story. | | api_name | Name of API for API enabled story. | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | draft_id | ID of the selected draft. | | draft_name | Name of the selected draft. | | pending_action_runs_count | Total number of pending action runs across all actions in the story. Only included when `include_live_activity=true` is set. | | concurrent_runs_count | Number of concurrent story runs currently executing. Only included when `include_live_activity=true` is set. | | tokens_used_percentage | Percentage of token limit used by the story. Only included when `include_live_activity=true` is set. | | not_working_actions_count | Number of actions in a "Not working" state in the story, meaning the action has not emitted an event since its last error log. Only included when `include_live_activity=true` is set. | ### Sample response ```json { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "send_to_story_skill_use_requires_confirmation": true, "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ], "api_enabled": false, "api_entry_actions": [], "api_exit_actions": [], "api_name": null, "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "draft_id": 1234, "draft_name": "Initial Draft", "pending_action_runs_count": 150, "concurrent_runs_count": 3, "tokens_used_percentage": 15.7 } ``` ### Update ## Description Update a story. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided. ## Request HTTP Method: **PUT** | Query Parameter | Description | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | **Optional** The story name. | | description | **Optional** A user-defined description of the story. | | add_tag_names | **Optional** An array of tag names to add to the story. | | remove_tag_names | **Optional** An array of tag names to remove from the story. | | keep_events_for | **Optional** Event retention period in seconds:
1 hour: `3600`
6 hours: `21600`
1 day: `86400`
3 days: `259200`
7 days: `604800`
14 days: `1209600 `
30 days:`2592000`
60 days:`5184000`
90 days:`7776000`
180 days:`15552000`
365 days: `31536000` | | disabled | **Optional** Boolean flag indicating whether the story is disabled from running. | | locked | **Optional** Boolean flag indicating whether the story is locked, preventing edits. | | priority | **Optional** Boolean flag indicating whether story runs with high priority. | | webhook_api_enabled | **Optional** Boolean flag indicating if webhook API is enabled. If enabling, the `api_entry_action_id` and `api_exit_action_ids` parameters must also be specified. The `draft_id` can also be provided if the change is being made to a non-live story. | | api_entry_action_id | **Optional** The ID of the entry action for this API enabled story (action must be of type webhook). `api_exit_action_ids` must also be provided and `webhook_api_enabled` must be set to true. | | api_exit_action_ids | **Optional** An array of IDs describing exit actions for this API enabled story (actions must be message-only mode event transformation). `api_entry_action_id` must also be provided and `webhook_api_enabled` must be set to true. | | send_to_story_access_source | **Optional** `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating if send to story is enabled and where the send to story can be used. If enabling send to story, the `entry_action_id` and `exit_action_ids` parameters must also be specified. | | entry_action_id | **Optional** The ID of the entry action for this send to story enabled story (action must be of type webhook). `exit_action_ids` must also be provided and `send_to_story_access_source` must be set to `STS`, `STS_AND_WORKBENCH` or `WORKBENCH`. | | exit_action_ids | **Optional** An array of IDs describing exit actions for this send to story enabled story (actions must be message-only mode event transformation). `entry_action_id` must also be provided and `send_to_story_access_source` must be set to `STS`, `STS_AND_WORKBENCH` or `WORKBENCH`. | | send_to_story_access | **Optional** Controls who is allowed to send to this story (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). default to `TEAM`. If using `SPECIFIC_TEAMS` must also specify list of teams' slugs in `shared_team_slugs`. | | shared_team_slugs | **Optional** List of teams' slugs that can send to this story. Required to set `send_to_story_access` to `SPECIFIC_TEAMS`. Defaults to `[]` (empty array). | | send_to_story_skill_use_requires_confirmation | **Optional** Boolean flag indicating whether workbench should ask for confirmation before running this story. Story must be enabled for workbench or send to story and workbench. | | team_id | **Optional** The ID of the team to move the story to. | | folder_id | **Optional** The ID of the folder to move the story to, or an empty value to indicate the root folder. Note that this folder must exist within the team identified by `team_id`, or the story's current team if `team_id` isn't specified. | | change_control_enabled | **Optional** Boolean flag indicating if change control is enabled. | | draft_id | **Optional** The ID of the draft to update. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | monitor_failures | **Optional** Boolean flag indicating if monitor failures is enabled on the story. | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X PUT \ https:///api/v1/stories/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated Simple story", "description": "Updates story description" }' ``` ## Response A successful request will return a JSON object describing the updated story ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if send to story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 timestamp representing date and time the story was created. | | updated_at | ISO 8601 timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | draft_id | ID of the updated draft. | | draft_name | Name of the updated draft. | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | ### Sample response ```json { "name": "Updated Simple story", "user_id": 167, "description": "Updates story description", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "draft_id": 1234, "draft_name": "Updated Draft", "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ] } ``` ### Sample request to enable send to story ```bash curl -X PUT \ https:///api/v1/stories/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "entry_action_id": "<>", "exit_action_ids": ["<>"], "send_to_story_access_source": "STS" }' ``` ### List ## Description Retrieve a list of stories. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | **Optional** Return stories belonging to this team. | | folder_id | **Optional** Return stories in this folder. | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | tags | **Optional** An array of tag names to filter by | | search | **Optional** A string that searches against story name | | filter | **Optional** Filter by one of: `SEND_TO_STORY_ENABLED`, `HIGH_PRIORITY`, `API_ENABLED`, `PUBLISHED` (deprecated), `FAVORITE`, `CHANGE_CONTROL_ENABLED`, `CHANGE_CONTROL_DISABLED`, `ENABLED`, `DISABLED`, `LOCKED` | | order | **Optional** Order the results by one of: `NAME`, `NAME_DESC`, `RECENTLY_EDITED`, `LEAST_RECENTLY_EDITED`, `ACTION_COUNT_ASC`, `ACTION_COUNT_DESC`, `CONCURRENT_RUNS_COUNT_DESC`, `PENDING_ACTION_RUNS_COUNT_DESC`, `NOT_WORKING_ACTIONS_COUNT_DESC` | | include_live_activity | **Optional** When set to `true`, includes live activity metrics like `pending_action_runs_count`, `concurrent_runs_count`, `tokens_used_percentage`, and `not_working_actions_count`. Defaults to `false`. | ```bash curl -X GET \ https:///api/v1/stories?include_live_activity=true \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing stories in the Tines tenant. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. Only `LIVE` stories will be listed. | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | | pending_action_runs_count | Total number of pending action runs across all actions in the story. Only included when `include_live_activity=true` is set. | | concurrent_runs_count | Number of concurrent story runs currently executing. Only included when `include_live_activity=true` is set. | | tokens_used_percentage | Percentage of token limit used by the story. Only included when `include_live_activity=true` is set. | | not_working_actions_count | Number of actions in a "Not working" state in the story, meaning the action has not emitted an event since its last error log. Only included when `include_live_activity=true` is set. | ### Sample response ```json { "stories": [ { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ], "pending_action_runs_count": 150, "concurrent_runs_count": 3, "tokens_used_percentage": 15.7 } ], "meta": { "current_page": "https:///api/v1/stories?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, // Max: 500 "pages": 1, "count": 1 } } ``` ### List pending actions ## Description Retrieve a list of actions in a story that currently have pending action runs, ordered by the number of pending runs (highest first). This endpoint is useful for monitoring which actions in a story have a backlog of work to process. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | | Query Parameter | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | search | **Optional** Search against action names. | | story_mode | **Optional** The mode (`TEST` or `LIVE`) of the story. Defaults to `LIVE`. | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | draft_id | **Optional** Return actions for a specific draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ```bash curl -X GET \ https:///api/v1/stories/<>/pending_actions?story_mode=LIVE \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing the actions with pending runs for the specified story, ordered by pending run count (descending). ### Field description | Parameter | Description | | ------------------------- | ---------------------------------------------- | | id | Action ID. | | name | Name of the action. | | type | Action type. | | pending_action_runs_count | Number of pending action runs for this action. | ### Sample response ```json { "pending_actions": [ { "id": 12345, "name": "Process webhook", "type": "Agents::EventTransformationAgent", "pending_action_runs_count": 150 }, { "id": 12346, "name": "Send notification", "type": "Agents::HTTPRequestAgent", "pending_action_runs_count": 45 }, { "id": 12347, "name": "Parse data", "type": "Agents::EventTransformationAgent", "pending_action_runs_count": 12 } ], "meta": { "current_page": "https:///api/v1/stories/<>/pending_actions?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 } } ``` ### Delete ## Description Delete a story. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ------------------------------ | | story_id | The ID of the story to delete. | ```bash curl -X DELETE \ https:///api/v1/stories/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Batch delete ## Description Delete many stories. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | --------------------------------- | | ids | The IDs of the stories to delete. | ```bash curl -X DELETE \ https:///api/v1/stories/batch \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "ids": [3, 4, 5] }' ``` ## Response A successful request will return an empty response with a `204` status code. ### Export ## Description Export a story to a transferable story file. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ------------------------------ | | story_id | The ID of the story to export. | | Query Parameter | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | randomize_urls | **Optional** Boolean flag indicating whether the story's page and webhook urls should be randomized. | | clear_recipients | **Optional** Boolean flag indicating whether the story's monitoring and email recipient fields should be cleared. | | draft_id | **Optional** The ID of the draft to export. | ```bash curl -X GET \ https:///api/v1/stories/<>/export \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the story in exported form. ### Sample response ```json { "schema_version": 18, "standard_lib_version": 41, "action_runtime_version": 6, "name": "Simple story", "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant. The alert will contain the type of alert (infection, ddos, credential stuffing, etc.) and details on any users affected. If the alert is related to an infection, based on the users job title, we will take a specific action.\r\n\r\nThe simple story is described in detail in the Tines Docs(https://hub.tines.com/docs/quickstart/simple-story/).\r\n\r\nUse the following URL command (replace $webhook-url with the webhook URL in the ''Summary\" tab of the 'Receive events' action) to send events to this story:\r\n\r\ncurl $webhook-url -X POST -H \"Content-Type: application/json\" -d '{\"event_name\":\"My first event\",\"type\":\"infection\",\"users\":[{\"name\":\"alice\",\"age\":25,\"country\":\"US\",\"job\":\"Engineer\"},{\"name\":\"bob\",\"age\":20,\"country\":\"UK\",\"job\":\"Student\"},{\"name\":\"carol\",\"age\":61,\"country\":\"Ireland\",\"job\":\"CEO\"}]}'", "guid": "8de58314250ff167127d6ae213711de9", "slug": "simple_story", "agents": [ { "type": "Agents::TriggerAgent", "name": "User is ceo", "disabled": false, "description": null, "guid": "9fda86d826c2da6b1001d83de774e6cd", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "ceo", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::EmailAgent", "name": "Notify by email", "disabled": false, "description": null, "guid": "2a1c3710c175566adbac7bdfcb8aa0af", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "recipients": "tinesdemouser@outlook.com", "subject": "Engineer in infected", "body": "Hello,

An alert has been detected that relates to an infected engineer. The user's details are shown below:
Name: <>
Age: <>
Country: <>

Thanks!" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null, "schedule": null }, { "type": "Agents::WebhookAgent", "name": "Receive events", "disabled": false, "description": null, "guid": "2f1f4538338172e208f653d3a614afb6", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "secret": "201367c22bd83f4e79ac81aa9f9efb7c", "verbs": "post", "path": "faac546b6297d276b866af0487343601", "include_headers": "false" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::TriggerAgent", "name": "Type is infection", "disabled": false, "description": null, "guid": "e606d66f945ba059655a672497d78170", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "infection", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::EventTransformationAgent", "name": "Explode users", "disabled": false, "description": null, "guid": "51ce4f788c04cf81dc7eb7dda25f575b", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "mode": "explode", "path": "=receive_events.users", "to": "user" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null, "schedule": null }, { "type": "Agents::TriggerAgent", "name": "User is student", "disabled": false, "description": null, "guid": "845aa2aa857ffe8832856050abf7d994", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "student", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::TriggerAgent", "name": "User is engineer", "disabled": false, "description": null, "guid": "bded45ec772c9f48984d39da6388ff56", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "engineer", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::HTTPRequestAgent", "name": "Send a post request", "disabled": false, "description": null, "guid": "dbe0171f0253ebde721ddfb086c323a5", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "url": "https://postman-echo.com/post", "content_type": "json", "method": "post", "payload": { "name": "<>", "age": "<>", "country": "<>", "job": "<>" }, "log_error_on_status": [] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null, "schedule": null } ], "diagram_notes": [], "links": [ { "source": 0, "receiver": 7 }, { "source": 2, "receiver": 3 }, { "source": 3, "receiver": 4 }, { "source": 4, "receiver": 6 }, { "source": 4, "receiver": 5 }, { "source": 4, "receiver": 0 }, { "source": 6, "receiver": 1 } ], "diagram_layout": "{\"9fda86d826c2da6b1001d83de774e6cd\":[105,-195],\"2a1c3710c175566adbac7bdfcb8aa0af\":[345,-120],\"2f1f4538338172e208f653d3a614afb6\":[345,-435],\"e606d66f945ba059655a672497d78170\":[345,-360],\"51ce4f788c04cf81dc7eb7dda25f575b\":[345,-285],\"845aa2aa857ffe8832856050abf7d994\":[570,-195],\"bded45ec772c9f48984d39da6388ff56\":[345,-195],\"dbe0171f0253ebde721ddfb086c323a5\":[105,-120]}", "send_to_story_enabled": false, "send_to_story_skill_use_requires_confirmation": true, "entry_agent_guid": null, "exit_agent_guids": [], "exit_agent_guid": null, "api_entry_action_guids": [], "api_exit_action_guids": [], "keep_events_for": 86400, "reporting_status": true, "send_to_story_access": null, "story_library_metadata": {}, "monitor_failures": false, "send_to_stories": [], "form": null, "synchronous_webhooks_enabled": false, "forms": [], "pages": [], "tags": [], "time_saved_unit": "minutes", "time_saved_value": 0, "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "integration_product": null, "integration_vendor": null, "exported_at": "2023-12-15T01:43:37Z", "integrations": [] } ``` ### Import ## Description Import a new story. Note that if the story data includes embedded substories these will not be imported. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | new_name | The new name for the story. | | data | JSON object representing the story in [exported form](/api/stories/export#sample-response) | | team_id | ID of team to which the story should be added. | | folder_id | **Optional** ID of folder to which the story should be added. | | mode | **Optional** Create a new story or update existing by Name (`new`, `versionReplace`) default: `new` | ```bash curl -X POST \ https:///api/v1/stories/import \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "new_name": "Imported story", "team_id": 2, "folder_id": 1, "data": { "schema_version": 18, "standard_lib_version": 41, "action_runtime_version": 6, "name": "Simple story", "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant. The alert will contain the type of alert (infection, ddos, credential stuffing, etc.) and details on any users affected. If the alert is related to an infection, based on the users job title, we will take a specific action.\r\n\r\nThe simple story is described in detail in the Tines Docs(https://hub.tines.com/docs/quickstart/simple-story/).\r\n\r\nUse the following URL command (replace $webhook-url with the webhook URL in the ''Summary\" tab of the 'Receive events' action) to send events to this story:\r\n\r\ncurl $webhook-url -X POST -H \"Content-Type: application/json\" -d '{\"event_name\":\"My first event\",\"type\":\"infection\",\"users\":[{\"name\":\"alice\",\"age\":25,\"country\":\"US\",\"job\":\"Engineer\"},{\"name\":\"bob\",\"age\":20,\"country\":\"UK\",\"job\":\"Student\"},{\"name\":\"carol\",\"age\":61,\"country\":\"Ireland\",\"job\":\"CEO\"}]}'", "guid": "8de58314250ff167127d6ae213711de9", "slug": "simple_story", "agents": [ { "type": "Agents::TriggerAgent", "name": "User is ceo", "disabled": false, "description": null, "guid": "9fda86d826c2da6b1001d83de774e6cd", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "ceo", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::EmailAgent", "name": "Notify by email", "disabled": false, "description": null, "guid": "2a1c3710c175566adbac7bdfcb8aa0af", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "recipients": "tinesdemouser@outlook.com", "subject": "Engineer in infected", "body": "Hello,

An alert has been detected that relates to an infected engineer. The user'\''s details are shown below:
Name: <>
Age: <>
Country: <>

Thanks!" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null, "schedule": null }, { "type": "Agents::WebhookAgent", "name": "Receive events", "disabled": false, "description": null, "guid": "2f1f4538338172e208f653d3a614afb6", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "secret": "201367c22bd83f4e79ac81aa9f9efb7c", "verbs": "post", "path": "faac546b6297d276b866af0487343601", "include_headers": "false" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::TriggerAgent", "name": "Type is infection", "disabled": false, "description": null, "guid": "e606d66f945ba059655a672497d78170", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "infection", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::EventTransformationAgent", "name": "Explode users", "disabled": false, "description": null, "guid": "51ce4f788c04cf81dc7eb7dda25f575b", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "mode": "explode", "path": "=receive_events.users", "to": "user" }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null, "schedule": null }, { "type": "Agents::TriggerAgent", "name": "User is student", "disabled": false, "description": null, "guid": "845aa2aa857ffe8832856050abf7d994", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "student", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::TriggerAgent", "name": "User is engineer", "disabled": false, "description": null, "guid": "bded45ec772c9f48984d39da6388ff56", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "rules": [ { "type": "regex", "value": "engineer", "path": "<>" } ] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null }, { "type": "Agents::HTTPRequestAgent", "name": "Send a post request", "disabled": false, "description": null, "guid": "dbe0171f0253ebde721ddfb086c323a5", "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "options": { "url": "https://postman-echo.com/post", "content_type": "json", "method": "post", "payload": { "name": "<>", "age": "<>", "country": "<>", "job": "<>" }, "log_error_on_status": [] }, "reporting": { "time_saved_value": 0, "time_saved_unit": "minutes" }, "monitoring": { "monitor_all_events": false, "monitor_failures": false, "monitor_no_events_emitted": null }, "template": { "created_from_template_guid": null, "created_from_template_version": null }, "width": null, "schedule": null } ], "diagram_notes": [], "links": [ { "source": 0, "receiver": 7 }, { "source": 2, "receiver": 3 }, { "source": 3, "receiver": 4 }, { "source": 4, "receiver": 6 }, { "source": 4, "receiver": 5 }, { "source": 4, "receiver": 0 }, { "source": 6, "receiver": 1 } ], "diagram_layout": "{\"9fda86d826c2da6b1001d83de774e6cd\":[105,-195],\"2a1c3710c175566adbac7bdfcb8aa0af\":[345,-120],\"2f1f4538338172e208f653d3a614afb6\":[345,-435],\"e606d66f945ba059655a672497d78170\":[345,-360],\"51ce4f788c04cf81dc7eb7dda25f575b\":[345,-285],\"845aa2aa857ffe8832856050abf7d994\":[570,-195],\"bded45ec772c9f48984d39da6388ff56\":[345,-195],\"dbe0171f0253ebde721ddfb086c323a5\":[105,-120]}", "send_to_story_enabled": false, "send_to_story_skill_use_requires_confirmation": true, "entry_agent_guid": null, "exit_agent_guids": [], "exit_agent_guid": null, "api_entry_action_guids": [], "api_exit_action_guids": [], "keep_events_for": 86400, "reporting_status": true, "send_to_story_access": null, "story_library_metadata": {}, "monitor_failures": false, "send_to_stories": [], "form": null, "synchronous_webhooks_enabled": false, "forms": [], "pages": [], "tags": [], "time_saved_unit": "minutes", "time_saved_value": 0, "origin_story_identifier": "cloud:72d8681fa16f17c9cb1b5d0118f96474:8de58314250ff167127d6ae213711de9", "integration_product": null, "integration_vendor": null, "exported_at": "2023-12-15T01:43:37Z", "integrations": [] } } }' ``` ## Response A successful request will return a JSON object describing the newly created story ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | monitor_failures | Boolean flag indicating if monitor failures is enabled on the story. | | recipients | List of monitoring recipients for the story. | ### Sample response ```json { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "monitor_failures": false, "recipients": [ { "address": "test@example.com" } ] } ``` ### Actions #### Create ## Description Use a HTTP POST request to create an action. Story or Group ID must be provided. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided. > **Note**: The Condition action was previously named 'Trigger' in Tines. To prevent workflow breakage, it is still referenced as `Agents::TriggerAgent` in API requests. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | Type of action to create:
`Agents::EmailAgent`
`Agents::EventTransformationAgent`
`Agents::HTTPRequestAgent`
`Agents::IMAPAgent`
`Agents::LLMAgent`
`Agents::TriggerAgent`
`Agents::WebhookAgent`
`Agents::SendToStoryAgent`
`Agents::GroupAgent`
| | name | Name of the action. | | options | JSON Options block of the action. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | **Optional** ID of story to which the action should be added. | | group_id | **Optional** ID of group to which the action should be added. | | description | **Optional** A user-defined description of the action. | | disabled | **Optional** Boolean flag indicating whether action is disabled. Defaults to `false`. | | source_ids | **Optional** Array of action IDs the action should receive emitted events from. | | links_to_sources | **Optional** Array of objects representing links to source actions. Mutually exclusive with source_ids field. Each object has source_id (required) and type (optional; "DEFAULT", "NO_MATCH", or "FAILURE") | | receiver_ids | **Optional** Array of action IDs the action should emit events to. | | links_to_receivers | **Optional** Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids field. Each object has receiver_id (required) and type (optional; "DEFAULT", "NO_MATCH", or "FAILURE") | | schedule | **Optional** An object defining the cron schedule for the action. | | monitor_failures | **Optional** Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | **Optional** Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | **Optional** Duration in seconds. If no events are emitted in this time, a notification will be sent. | | draft_id | **Optional** ID of the draft to which the action should be added. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ### Sample request ```bash curl -X POST \ https:///api/v1/actions \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "type":"Agents::EventTransformationAgent", "name": "Extract email addresses and urls", "story_id":"{{.story_id}}", "source_ids": [100, 102], "receiver_ids":[], "position": {"x": 100, "y": 200}, "options":{ "mode": "extract", "matchers": [ { "path": "{{.text}}", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "{{.text}}", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message" }, "links_to_sources": [ { "source_id": 10 }, { "source_id": 11, "type": "NO_MATCH" } ], "draft_id": 12345 }' ``` ## Response A successful request will return a JSON object describing the created action. ### Field description | Parameter | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | guid | Unique identifier of the action. | | group_id | ID of group to which the action belongs. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | | draft_id | ID of the draft to which the action belongs. | | draft_name | Name of the draft to which the action belongs. | ### Sample response ```json { "id": 73563, "type": "Agents::EventTransformationAgent", "user_id": 167, "options": { "mode": "extract", "matchers": [ { "path": "", "regexp": "\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,4}\b", "to": "email_addresses" }, { "path": "", "regexp": "https?://[S]+", "to": "urls" } ], "message": "This is an optional message" }, "name": "Extract email addresses and urls", "description": null, "schedule": null, "blended_events_count": 0, "logs_count": 0, "last_check_at": null, "last_receive_at": null, "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": null, "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "group_id": null, "position": { "x": 105, "y": 195 }, "receivers": [70118], "sources": [70116], "team_id": 335, "monitor_failures": false, "monitor_all_events": false, "monitor_no_events_emitted": null, "time_saved_unit": "minutes", "time_saved_value": 0, "page": null, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" }, "draft_id": 12345, "draft_name": "Initial Draft" } ``` #### Get ## Description Retrieve details of a specific action. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ---------------- | | action_id | ID of the action | | Query Parameter | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------- | | include_live_activity | **Optional** When set to `true`, includes live activity metrics like `pending_action_runs_count`. Defaults to `false`. | ```bash curl -X GET \ https:///api/v1/actions/<>?include_live_activity=true \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the requested action. ### Field description | Parameter | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | guid | Unique identifier of the action. | | group_id | ID of group to which the action belongs. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | | story_run_save_setting | An object containing the story run save settings for this action. Only present for Receive Email and Webhook agents. [About story runs](https://www.tines.com/docs/stories/story-runs/#save-story-runs) | | pending_action_runs_count | Number of pending action runs for this action. Only included when `include_live_activity=true` is set. | ### Sample response ```json { "id": 73563, "type": "Agents::EventTransformationAgent", "user_id": 167, "options": { "mode": "deduplicate", "path": "{{.propagation_webhook.password}}", "lookback": "1" }, "name": "Deduplicate", "schedule": [ { "cron": "*/1 * * * *", "timezone": "Europe/Dublin" } ], "blended_events_count": 2, "logs_count": 4, "last_check_at": "2021-05-07T11:46:50Z", "last_receive_at": "2021-05-07T11:46:50Z", "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": "2021-05-07T11:47:00Z", "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "group_id": null, "position": { "x": -945, "y": 450 }, "receivers": [70118], "sources": [70116], "story_id": 807, "story_mode": "LIVE", "team_id": 335, "monitor_failures": true, "monitor_all_events": true, "monitor_no_events_emitted": 86400, "time_saved_unit": "minutes", "time_saved_value": 10, "page": null, "action_memory_contents": { "values": [] }, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" }, "pending_action_runs_count": 42 } ``` #### Update ## Description Update an action. ## Request HTTP Method: **PUT** | Parameter | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action_id | ID of the action | | name | **Optional** Name of the action. | | description | **Optional** A user-defined description of the action. | | options | **Optional** JSON Options block of the action. | | position | **Optional** An object describing the XY coordinates of the action on the story diagram. | | source_ids | **Optional** Array of action IDs the action should receive emitted events from. | | links_to_sources | **Optional** Array of objects representing links to source actions. Mutually exclusive with source_ids field. Each object has source_id (required) and type (optional, "DEFAULT" or "NO_MATCH") | | receiver_ids | **Optional** Array of action IDs the action should emit events to. | | links_to_receivers | **Optional** Array of objects representing links to receiver actions. Mutually exclusive with receiver_ids field. Each object has receiver_id (required) and type (optional, "DEFAULT" or "NO_MATCH") | | schedule | **Optional** An object defining the cron schedule for the action. | | disabled | **Optional** Boolean flag indicating whether action is disabled. | | monitor_failures | **Optional** Boolean flag indicating if a notification should be sent when this action fails. **NOTE** You must include the monitor_all_events parameter if updating this value | | monitor_all_events | **Optional** Boolean flag indicating if all events should be monitored. **NOTE** You must include the monitor_failures parameter if updating this value | | monitor_no_events_emitted | **Optional** Duration in seconds. If no events are emitted in this time, a notification will be sent. **NOTE** You must include both the monitor_failures and monitor_all_event parameters if updating this value | | num_runs_to_save | **Optional** Number of story runs to save for this action. Only present for Receive Email and Webhook agents. [About story runs](https://www.tines.com/docs/stories/story-runs/#save-story-runs) | ```bash curl -X PUT \ https:///api/v1/actions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "New action name" }' ``` ### Add links with types ```bash curl -v -X PUT \ "https:///api/v1/actions/<>" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "links_to_receivers": [ { "receiver_id": "<>", "type": "NO_MATCH" } ] }' ``` ## Response A successful request will return a JSON object describing the updated action. ### Field description | Parameter | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | guid | Unique identifier of the action. | | group_id | ID of group to which the action belongs. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | | story_run_save_setting | An object containing the story run save settings for this action. Only present for Receive Email and Webhook agents. [About story runs](https://www.tines.com/docs/stories/story-runs/#save-story-runs) | ### Sample response ```json { "id": 73563, "user_id": 167, "type": "Agents::EventTransformationAgent", "options": { "mode": "deduplicate", "path": "{{.propagation_webhook.password}}", "lookback": "1" }, "name": "New action name", "description": null, "schedule": [ { "cron": "*/1 * * * *", "timezone": "Europe/Dublin" } ], "blended_events_count": 2, "logs_count": 4, "last_check_at": "2021-05-07T11:46:50Z", "last_receive_at": "2021-05-07T11:46:50Z", "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": "2021-05-07T11:47:00Z", "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "group_id": null, "position": { "x": -945, "y": 450 }, "receivers": [70118], "sources": [70116], "story_id": 807, "story_mode": "LIVE", "team_id": 335, "monitor_failures": true, "monitor_all_events": true, "monitor_no_events_emitted": 86400, "time_saved_unit": "minutes", "time_saved_value": 10, "page": null, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" } } ``` #### List ## Description Retrieve a list of actions available in the Tines tenant. ## Request HTTP Method: **GET** | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | story_id | **Optional** List actions for the given story | | story_mode | **Optional** List actions for the given story mode (must be used with story_id) | | team_id | **Optional** List actions for the given team | | group_id | **Optional** List actions for the given group | | action_type | **Optional** Filter actions by the given type:
`Agents::EmailAgent`
`Agents::EventTransformationAgent`
`Agents::HTTPRequestAgent`
`Agents::IMAPAgent`
`Agents::TriggerAgent`
`Agents::WebhookAgent`
`Agents::SendToStoryAgent`
`Agents::GroupAgent`
`Agents::LLMAgent`
| | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | draft_id | **Optional** List actions for the given draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | include_live_activity | **Optional** When set to `true`, includes live activity metrics like `pending_action_runs_count`. Defaults to `false`. | ```bash curl -X GET \ https:///api/v1/actions?include_live_activity=true \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing actions in the Tines tenant. ### Field description | Parameter | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | guid | Unique identifier of the action. | | group_id | ID of group to which the action belongs. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | | draft_id | ID of the draft associated with the action. | | draft_name | Name of the draft associated with the action. | | story_run_save_setting | An object containing the story run save settings for this action. Only present for Receive Email and Webhook agents. [About story runs](https://www.tines.com/docs/stories/story-runs/#save-story-runs) | | pending_action_runs_count | Number of pending action runs for this action. Only included when `include_live_activity=true` is set. | ### Sample response ```json { "agents": [ { "id": 73563, "type": "Agents::EventTransformationAgent", "user_id": 167, "options": { "mode": "deduplicate", "path": "{{.propagation_webhook.password}}", "lookback": "1" }, "name": "Deduplicate", "schedule": [ { "cron": "*/1 * * * *", "timezone": "Europe/Dublin" } ], "blended_events_count": 2, "logs_count": 4, "last_check_at": "2021-05-07T11:46:50Z", "last_receive_at": "2021-05-07T11:46:50Z", "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": "2021-05-07T11:47:00Z", "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "group_id": null, "position": { "x": -945, "y": 450 }, "receivers": [70118], "sources": [70116], "story_id": 807, "story_mode": "LIVE", "team_id": 335, "monitor_failures": true, "monitor_all_events": true, "monitor_no_events_emitted": 86400, "time_saved_unit": "minutes", "time_saved_value": 10, "page": null, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" }, "draft_id": 12345, "draft_name": "Initial Draft", "pending_action_runs_count": 42 } ], "meta": { "current_page": "https:///api/v1/actions?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### List events ## Description Retrieve a list of events emitted by a specified action. ## Request HTTP Method: **GET** | Parameter | Description | | -------------------------- | --------------------------------------------------------------------------------------------------- | | action_id | ID of the action | | since_id | **Optional** Only retrieve events after this ID. | | until_id | **Optional** Only retrieve events until (and including) this ID. | | show_reemitted_events_only | **Optional** Only retrieve events that have been re-emitted. Boolean, defaults to `false`. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 500. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/actions/<>/events \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing events emitted by the specified action. ### Field description | Parameter | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | id | Event ID. | | agent_id | ID of action that emitted the event. | | payload | JSON representation of the event payload. | | created_at | ISO 8601 Timestamp representing date and time the event was emitted. | | updated_at | ISO 8601 Timestamp representing date and time the event was last updated. Will always be the same as 'created_at'. | | story_run_guid | Unique identifier of that event's story run. | | previous_events_ids | IDs of the upstream action's events in that event's story run. | | re_emitted | Boolean flag indicating whether this event has been re-emitted. | ### Sample response ```json { "events": [ { "id": 79240, "agent_id": 21, "payload": { "propagation_webhook": { "username": "joe.bloggs", "age": 99 }, "delay_http_request": { "body": { "delay": "5" }, "headers": { "access-control-allow-credentials": "", "access-control-allow-headers": "", "access-control-allow-methods": "", "access-control-allow-origin": "", "access-control-expose-headers": "", "content-type": "application/json; charset=utf-8", "date": "Tue, 03 Apr 2018 13:37:24 GMT", "etag": "W/\"d-N6WkUL2Jgn7fCGyPWbbptw\"", "server": "nginx", "set-cookie": "sails.sid=s%3A6Hr22AAbEOurnGiqRo3; Path=/; HttpOnly", "vary": "Accept-Encoding", "content-length": "13", "connection": "Close" }, "status": 200 } }, "created_at": "2018-04-03T13:37:24.479Z", "updated_at": "2018-04-03T13:37:24.479Z", "story_run_guid": "d59cd024-38b2-4287-b298-a8ee8dc86863", "previous_events_ids": [1785155927], "re_emitted": false } ], "meta": { "current_page": "https:///api/v1/agents/79240/events?page=1&per_page=20&", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Large payloads Please note that a response payload size exceeding 200MB will result in a 422 error. #### List logs ## Description List all logs emitted by a specific action. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ---------------- | | action_id | ID of the action | | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | level | **Optional** Filter logs by a given severity level (warning = 2, info = 3, error = 4). | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/actions/<>/logs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object listing the action logs. ### Field description | Parameter | Description | | ------------- | ------------------------------------------------------------------------- | | id | Action log ID. | | level | The severity level of the log (warning = 2, info = 3, error = 4). | | message | The log message. | | created_at | ISO 8601 Timestamp representing creation date and time of the action log. | | inbound_event | The inbound event for the action run. | ### Sample response ```json { "action_logs": [ { "id": 733, "level": 3, "message": "Sending request to https:///api/v1/stories/ with options: { \"url\": \"https:///api/v1/stories/\", \"params\": {}, \"body\": null, \"headers\": { \"content-type\": \"application/json\", \"Authorization\": \"Bearer ****************\", \"User-Agent\": \"Tines (Advanced Security Automation; tines.com)\", \"Content-Type\": null }, \"method\": \"get\" }", "created_at": "2023-12-20T14:41:15Z", "inbound_event": null }, ], "meta": { "current_page": "https:///api/v1/actions/<>/logs?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count":1 } } ``` #### Delete ## Description Delete a specific action. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ---------------- | | action_id | ID of the action | ```bash curl -X DELETE \ https:///api/v1/actions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete events ## Description Delete all events emitted by a specific action. ## Request HTTP Method: **DELETE** | Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------- | | action_id | ID of the action | | async_deletion | Boolean flag indicating if the deletion should be asynchronous by sending it to a background job. | ```bash curl -X DELETE \ https:///api/v1/actions/<>/remove_events \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the action with deleted events. ### Field description | Parameter | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | guid | Unique identifier of the action. | | group_id | ID of group to which the action belongs. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | ### Sample response ```json { "id": 73563, "type": "Agents::EventTransformationAgent", "user_id": 167, "options": { "mode": "deduplicate", "path": "<>", "lookback": "10" }, "name": "Deduplicate alerts", "description": null, "schedule": null, "blended_events_count": 0, "logs_count": 2, "last_check_at": null, "last_receive_at": "2023-12-11T20:13:57Z", "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": "2023-12-11T20:13:52Z", "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "group_id": null, "position": { "x": 105, "y": 195 }, "receivers": [70118], "sources": [70116], "team_id": 335, "monitor_failures": false, "monitor_all_events": false, "monitor_no_events_emitted": null, "time_saved_unit": "minutes", "time_saved_value": 0, "page": null, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" } } ``` #### Delete logs ## Description Delete all logs emitted by a specific action. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ---------------- | | action_id | ID of the action | ```bash curl -X DELETE \ https:///api/v1/actions/<>/remove_logs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the action with deleted logs. ### Field description | Parameter | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | guid | Unique identifier of the action. | | group_id | ID of group to which the action belongs. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | ### Sample response ```json { "id": 73563, "type": "Agents::EventTransformationAgent", "user_id": 167, "options": { "mode": "deduplicate", "path": "<>", "lookback": "10" }, "name": "Deduplicate alerts", "description": null, "schedule": null, "blended_events_count": 1, "logs_count": 0, "last_check_at": null, "last_receive_at": "2023-12-11T20:13:57Z", "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": "2023-12-11T20:13:52Z", "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "group_id": null, "position": { "x": 105, "y": 195 }, "receivers": [70118], "sources": [70116], "team_id": 335, "monitor_failures": false, "monitor_all_events": false, "monitor_no_events_emitted": null, "time_saved_unit": "minutes", "time_saved_value": 0, "page": null, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" } } ``` #### Clear memory ## Description Clear all the values stored in an action's memory of a specific action located on the 'Status' tab of the action. This is applicable for event transform actions in 'deduplicate' or 'implode' mode. Action Memory allows users to store information generated during the execution of event transform actions and then reference or manipulate that information in subsequent actions within a workflow. Clearing this data can be of benefit to a large story with many events. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ---------------- | | action_id | ID of the action | ```bash curl -X DELETE \ https:///api/v1/actions/<>/clear_memory \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the action with cleared memory. ### Field description | Parameter | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------- | | id | Action ID. | | type | Action type | | user_id | User ID of the action's owner. | | options | JSON Options block of the action. | | name | Name of the action. | | description | A user-defined description of the action. | | schedule | An object defining the cron schedule for the action. | | blended_events_count | Number of events action has emitted in both TEST and LIVE mode. | | logs_count | Number of logs action has stored. | | last_check_at | ISO 8601 Timestamp representing date and time of action's last scheduled run. | | last_receive_at | ISO 8601 Timestamp representing date and time of last event received. | | created_at | ISO 8601 Timestamp representing creation date and time of action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of action. | | last_event_at | ISO 8601 Timestamp representing date and time the last event was received. Updated at one-minute intervals. | | last_error_log_at | ISO 8601 Timestamp representing date and time of last error thrown by the action. | | disabled | Boolean flag indicating whether action is disabled. | | group_id | ID of group to which the action belongs. | | guid | Unique identifier of the action. | | position | An object describing the XY coordinates of the action on the story diagram. | | story_id | ID of story to which the action belongs. | | story_mode | Mode of the story to which the action belongs `LIVE` or `TEST` | | nested_group_id | ID of group contained in the action. | | team_id | ID of team to which the action belongs. | | sources | An Array of Action IDs this action receives emitted events from. | | receivers | An Array of Action IDs this action emits events to. | | monitor_failures | Boolean flag indicating if a notification should be sent when this action fails. | | monitor_all_events | Boolean flag indicating if all events should be monitored. | | monitor_no_events_emitted | Duration in seconds. If no events are emitted in this time, a notification will be sent. | | time_saved_unit | Unit of time corresponding to time saved value. | | time_saved_value | Number indicating the amount of time saved. | | page | An object with information on the associated page, if this is a page action | | action_memory_contents | An object containing an array of the values an action may be holding in its memory. | | slug | An underscored representation of the action's name | | links_to_sources | An array of links to source actions, including the source ID and the link type | | links_to_receivers | An array of links to receiver actions, including the receiver ID and the link type | ### Sample response ```json { "id": 73563, "type": "Agents::EventTransformationAgent", "user_id": 167, "options": { "mode": "deduplicate", "path": "<>", "lookback": "10" }, "name": "Deduplicate alerts", "description": null, "schedule": null, "blended_events_count": 1, "logs_count": 2, "last_check_at": null, "last_receive_at": "2023-12-11T20:13:57Z", "created_at": "2021-05-07T11:42:58Z", "updated_at": "2021-05-07T11:47:00Z", "last_event_at": "2023-12-11T20:13:52Z", "last_error_log_at": null, "disabled": false, "guid": "f3fe6f8e167c9db42e64eaef8e5d2f0c", "position": { "x": 105, "y": 195 }, "group_id": null, "receivers": [70118], "sources": [70116], "team_id": 335, "monitor_failures": false, "monitor_all_events": false, "monitor_no_events_emitted": null, "time_saved_unit": "minutes", "time_saved_value": 0, "page": null, "story_id": 807, "story_mode": "LIVE", "nested_group_id": null, "links_to_sources": { "source_id": 70116, "link_type": "DEFAULT" }, "links_to_receivers": { "receiver_id": 70118, "link_type": "NO_MATCH" } } ``` ### Change request #### Create ## Description Create a change request. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | title | **Optional** The change request name. | | description | **Optional** A user-defined description of the change request. For mentioning users, use the notation <@user-2435>, replacing '2435' with the user ID. | | draft_id | **Optional** The ID of the draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/change_request \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "title": "Sample Change Request", "description": "A sample change request" }' ``` ## Response A successful request will return a JSON object describing the change request ### Field description | Parameter | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The live story ID. | | draft_id | ID of the selected draft. | | draft_name | Name of the selected draft. | | change_request | The change request. This contains `id`, the ID of the request, `name`, the name of the request, `description`, the description of the request, `status`, the status of the request which is one of "PENDING" or "APPROVED", `participants`, an array of user IDs that made changes in the change request, and `live_story_export` and `draft_export` which capture the export of the live story and the draft respectively. | ### Sample response ```json { "id": 154, "draft_id": 1234, "draft_name": "Initial Draft", "change_request": { "id": 21, "name": "Change request name", "description": "Description of proposed changes", "status": "PENDING", "participants": [1, 2, 3], "live_story_export": "{\"schema_version\":26,\"standard_lib_version\":83,\"action_runtime_version\":35,\"name\":\"Story 1\",\"description\":\"Example description\",\"guid\":\"b20c18537050fcfbbf01b87ba3a82fef\",\"slug\":\"story_1\",\"agents\":[],\"diagram_notes\":[],\"links\":[],\"diagram_layout\":\"{}\",\"story_library_metadata\":{},\"monitor_failures\":false,\"synchronous_webhooks_enabled\":false,\"integrations\":[],\"parent_only_send_to_story\":false,\"keep_events_for\":604800,\"reporting_status\":true,\"send_to_story_enabled\":false,\"entry_agent_guid\":null,\"exit_agent_guids\":[],\"api_entry_action_guids\":[],\"api_exit_action_guids\":[],\"send_to_story_access\":null,\"send_to_story_access_source\":0,\"send_to_story_skill_use_requires_confirmation\":true,\"pages\":[],\"tags\":[],\"time_saved_unit\":\"minutes\",\"time_saved_value\":0,\"origin_story_identifier\":\"cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:b20c18537050fcfbbf01b87ba3a82fef\",\"recipients\":[\"person_1@example.com\"],\"integration_product\":null,\"integration_vendor\":null,\"llm_product_instructions\":\"\",\"exported_at\":\"2023-10-16T11:16:25Z\"}", "draft_export": "{\"schema_version\":26,\"standard_lib_version\":83,\"action_runtime_version\":35,\"name\":\"Story 1\",\"description\":\"Example description\",\"guid\":\"a8e4709bbede0ce3db932c863285a747\",\"slug\":\"story_1_test0\",\"agents\":[{\"type\":\"Agents::EventTransformationAgent\",\"name\":\"New action\",\"disabled\":false,\"description\":null,\"guid\":\"c7b71ef79ca29ae68b7763714c12dd05\",\"origin_story_identifier\":\"cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:a8e4709bbede0ce3db932c863285a747\",\"options\":{\"mode\":\"message_only\",\"loop\":false,\"payload\":{\"message\":\"This is an optional message\"}},\"reporting\":{\"time_saved_value\":0,\"time_saved_unit\":\"minutes\"},\"monitoring\":{\"monitor_all_events\":false,\"monitor_failures\":false,\"monitor_no_events_emitted\":null},\"template\":{\"created_from_template_guid\":null,\"created_from_template_version\":null,\"template_tags\":[]},\"width\":null,\"schedule\":null}],\"diagram_notes\":[],\"links\":[],\"diagram_layout\":\"{\\\"c7b71ef79ca29ae68b7763714c12dd05\\\":[300,300]}\",\"story_library_metadata\":{},\"monitor_failures\":false,\"synchronous_webhooks_enabled\":false,\"integrations\":[],\"parent_only_send_to_story\":false,\"keep_events_for\":604800,\"reporting_status\":true,\"send_to_story_enabled\":false,\"entry_agent_guid\":null,\"exit_agent_guids\":[],\"api_entry_action_guids\":[],\"api_exit_action_guids\":[],\"send_to_story_access\":null,\"send_to_story_access_source\":0,\"send_to_story_skill_use_requires_confirmation\":true,\"pages\":[],\"tags\":[],\"time_saved_unit\":\"minutes\",\"time_saved_value\":0,\"origin_story_identifier\":\"cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:b20c18537050fcfbbf01b87ba3a82fef\",\"recipients\":[\"person_1@example.com\"],\"integration_product\":null,\"integration_vendor\":null,\"llm_product_instructions\":\"\",\"exported_at\":\"2023-10-16T11:16:25Z\"}" } } ``` #### Generate a change request description ## Description Generate a new description for the changes captured in the change request. AI features must be enabled for a successful response. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------ | | draft_id | The ID of the draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X GET \ https:///api/v1/stories/<>/change_request/ai_description \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "draft_id": "<>" }' ``` ## Response A successful request will return a JSON object with the description of the changes captured in the change request. ### Field description | Parameter | Description | | ----------------------------- | ------------------------------------------------------------------------ | | change_request_ai_description | The generated description of the changes captured in the change request. | ### Sample response ```json { "change_request_ai_description": "Summary of changes" } ``` #### Approve ## Description Approve a change request. ## Request HTTP Method: **POST** | Query Parameter | Description | | ----------------- | ---------------------------- | | change_request_id | The ID of the change request | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/change_request/approve \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "change_request_id": "<>" }' ``` ## Response A successful request will return a JSON object with the status of the change request ### Field description | Parameter | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | draft_id | ID of the draft containing the change request. | | draft_name | Name of the draft containing the change request | | id | The live story ID. | | change_request | The change request. This contains `id`, the ID of the request, `status`, the status of the request which is one of "PENDING" or "APPROVED", and `participants`, an array of user IDs that made changes in the change request | ### Sample response ```json { "draft_id": 1234, "draft_name": "Initial draft", "change_request": { "id": 15, "status": "APPROVED", "participants": [1, 2, 3] }, "id": 154 } ``` #### Cancel ## Description Cancel a change request. ## Request HTTP Method: **POST** | Query Parameter | Description | | ----------------- | ---------------------------- | | change_request_id | The ID of the change request | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/change_request/cancel \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "change_request_id": "<>" }' ``` ## Response A successful request will return a JSON object that shows the change request has been deleted ### Field description | Parameter | Description | | -------------- | ------------------------------------------------------------ | | draft_id | ID of the draft containing the change request. | | draft_name | Name of the draft containing the change request. | | id | The live story ID. | | change_request | The change request, which will be `null` as it was canceled. | ### Sample response ```json { "draft_id": 1234, "draft_name": "Initial draft", "change_request": null, "id": 154 } ``` #### Promote ## Description Promote changes to the live story. ## Request HTTP Method: **POST** | Query Parameter | Description | | ----------------- | ---------------------------- | | change_request_id | The ID of the change request | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/change_request/promote \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "change_request_id": "<>" }' ``` ## Response A successful request will return a JSON object representing updated story. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | | api_enabled | Boolean flag indicating if Webhook API is enabled. | | api_entry_actions | Array of entry action ID for API enabled story. | | api_exit_actions | Array of exit action IDs for API enabled story. | | api_name | Name of API for API enabled story. | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | ### Sample response ```json { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "send_to_story_skill_use_requires_confirmation": true, "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ], "api_enabled": false, "api_entry_actions": [], "api_exit_actions": [], "api_name": null, "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1] } ``` #### View ## Description View the current change request for a story. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------- | | draft_id | **Optional** The ID of the draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X GET \ https:///api/v1/stories/<>/change_request/view \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return a JSON object describing the change request, if a change request exists. If a test story has changes but a change request has not been submitted for review, change_request will be null. ### Field description | Parameter | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The live story ID. | | draft_id | ID of the selected draft. | | draft_name | Name of the selected draft. | | change_request | The change request. This contains `id`, the ID of the request, `name`, the name of the request, `description`, the description of the request, `status`, the status of the request which is one of "PENDING" or "APPROVED", `participants`, an array of user IDs that made changes in the change request, and `live_story_export` and `draft_export` which capture the export of the live story and the draft respectively. | ### Sample response ```json { "id": 154, "draft_id": 1234, "draft_name": "Initial Draft", "change_request": { "id": 21, "name": "Change request name", "description": "Description of proposed changes", "status": "PENDING", "participants": [1, 2, 3], "live_story_export": "{\"schema_version\":26,\"standard_lib_version\":83,\"action_runtime_version\":35,\"name\":\"Story 1\",\"description\":\"Example description\",\"guid\":\"b20c18537050fcfbbf01b87ba3a82fef\",\"slug\":\"story_1\",\"agents\":[],\"diagram_notes\":[],\"links\":[],\"diagram_layout\":\"{}\",\"story_library_metadata\":{},\"monitor_failures\":false,\"synchronous_webhooks_enabled\":false,\"integrations\":[],\"parent_only_send_to_story\":false,\"keep_events_for\":604800,\"reporting_status\":true,\"send_to_story_enabled\":false,\"entry_agent_guid\":null,\"exit_agent_guids\":[],\"api_entry_action_guids\":[],\"api_exit_action_guids\":[],\"send_to_story_access\":null,\"send_to_story_access_source\":0,\"send_to_story_skill_use_requires_confirmation\":true,\"pages\":[],\"tags\":[],\"time_saved_unit\":\"minutes\",\"time_saved_value\":0,\"origin_story_identifier\":\"cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:b20c18537050fcfbbf01b87ba3a82fef\",\"recipients\":[\"person_1@example.com\"],\"integration_product\":null,\"integration_vendor\":null,\"llm_product_instructions\":\"\",\"exported_at\":\"2023-10-16T11:16:25Z\"}", "draft_export": "{\"schema_version\":26,\"standard_lib_version\":83,\"action_runtime_version\":35,\"name\":\"Story 1\",\"description\":\"Example description\",\"guid\":\"a8e4709bbede0ce3db932c863285a747\",\"slug\":\"story_1_test0\",\"agents\":[{\"type\":\"Agents::EventTransformationAgent\",\"name\":\"New action\",\"disabled\":false,\"description\":null,\"guid\":\"c7b71ef79ca29ae68b7763714c12dd05\",\"origin_story_identifier\":\"cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:a8e4709bbede0ce3db932c863285a747\",\"options\":{\"mode\":\"message_only\",\"loop\":false,\"payload\":{\"message\":\"This is an optional message\"}},\"reporting\":{\"time_saved_value\":0,\"time_saved_unit\":\"minutes\"},\"monitoring\":{\"monitor_all_events\":false,\"monitor_failures\":false,\"monitor_no_events_emitted\":null},\"template\":{\"created_from_template_guid\":null,\"created_from_template_version\":null,\"template_tags\":[]},\"width\":null,\"schedule\":null}],\"diagram_notes\":[],\"links\":[],\"diagram_layout\":\"{\\\"c7b71ef79ca29ae68b7763714c12dd05\\\":[300,300]}\",\"story_library_metadata\":{},\"monitor_failures\":false,\"synchronous_webhooks_enabled\":false,\"integrations\":[],\"parent_only_send_to_story\":false,\"keep_events_for\":604800,\"reporting_status\":true,\"send_to_story_enabled\":false,\"entry_agent_guid\":null,\"exit_agent_guids\":[],\"api_entry_action_guids\":[],\"api_exit_action_guids\":[],\"send_to_story_access\":null,\"send_to_story_access_source\":0,\"send_to_story_skill_use_requires_confirmation\":true,\"pages\":[],\"tags\":[],\"time_saved_unit\":\"minutes\",\"time_saved_value\":0,\"origin_story_identifier\":\"cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:b20c18537050fcfbbf01b87ba3a82fef\",\"recipients\":[\"person_1@example.com\"],\"integration_product\":null,\"integration_vendor\":null,\"llm_product_instructions\":\"\",\"exported_at\":\"2023-10-16T11:16:25Z\"}" } } ``` ### Disable ## Description Update the disabled state of a story. This method can be used to disable a story that has change control enabled, bypassing the change control approval process. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ------------------------------------------------------------ | | id | The ID of the story to update. | | disabled | Boolean flag indicating the new disabled state of the story. | ```bash curl -X POST \ https:///api/v1/stories/<>/disable \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{"disabled": true}' ``` ## Response A successful request will return a JSON object representing the specified disabled state. ### Field description | Parameter | Description | | --------- | -------------------------------------------------------- | | disabled | Boolean flag indicating the disabled state of the story. | ### Sample response ```json { "disabled": true } ``` ### Drafts #### Create ## Description Create a new draft for a story. ## Request HTTP Method: **POST** | Path Parameter | Description | | -------------- | --------------- | | story_id | ID of the story | | Query Parameter | Description | | --------------- | ----------------- | | name | Name of the draft | ```bash curl -X POST \ https:///api/v1/stories/<>/drafts \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "My draft", }' ``` ## Response A successful request will return a JSON object describing the created draft. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The draft ID | | name | The draft name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. Will update if the draft updates the story name. Includes a draft-specific suffix. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | Legacy field, always `TEST`. | | story_id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | ### Sample response ```json { "name": "My draft", "id": 100, "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "TEST", "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "story_name": "My story", "story_id": 99, "slug": "my_story_test0" } ``` #### List ## Description Retrieve a list of drafts for a story. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | --------------- | | story_id | ID of the story | ```bash curl -X GET \ https:///api/v1/stories/<>/drafts \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON array describing drafts for that Tines story. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The draft ID | | name | The draft name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. Will update if the draft updates the story name. Includes a draft-specific suffix. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | Legacy field, always `TEST`. | | story_id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | ### Sample response ```json { "drafts": [ { "name": "My draft", "id": 100, "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "TEST", "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "story_name": "My story", "story_id": 99, "slug": "my_story_test0" }, { "name": "My other draft", "id": 101, "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "TEST", "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "story_name": "My story", "story_id": 99, "slug": "my_story_test1" } ], "meta": { "current_page": "https:///api/v1/stories/99/drafts?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, // Max: 500 "pages": 1, "count": 2 } } ``` #### Delete ## Description Delete a draft for a story. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | --------------- | | story_id | ID of the story | | draft_id | ID of the draft | ```bash curl -X DELETE \ https:///api/v1/stories/<>/drafts/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a 204 (no content) response. ### Events #### Get ## Description Retrieve an event. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | -------------------------------- | | event_id | The ID of the event to retrieve. | ```bash curl -X GET \ https:///api/v1/events/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified event. ### Field description | Parameter | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | id | Event ID. | | agent_id | ID of action that emitted the event. | | payload | JSON representation of the event payload. | | created_at | ISO 8601 Timestamp representing date and time the event was emitted. | | updated_at | ISO 8601 Timestamp representing date and time the event was last updated. Will always be the same as 'created_at'. | | story_run_guid | Unique identifier of that event's story run. | | previous_events_ids | IDs of the upstream action's events in that event's story run. | | re_emitted | Boolean flag indicating whether this event has been re-emitted. | ### Sample response ```json { "id": 1785421735, "user_id": 1, "agent_id": 21, "payload": { "propagation_webhook": { "username": "joe.bloggs", "age": 99 }, "delay_http_request": { "body": { "delay": "5" }, "headers": { "access-control-allow-credentials": "", "access-control-allow-headers": "", "access-control-allow-methods": "", "access-control-allow-origin": "", "access-control-expose-headers": "", "content-type": "application/json; charset=utf-8", "date": "Tue, 03 Apr 2018 13:37:24 GMT", "etag": "W/\"d-N6WkUL2Jgn7fCGyPWbbptw\"", "server": "nginx", "set-cookie": "sails.sid=s%3A6Hr22AAbEOurnGiqRo3; Path=/; HttpOnly", "vary": "Accept-Encoding", "content-length": "13", "connection": "Close" }, "status": 200 } }, "created_at": "2018-04-03T13:37:24.479Z", "updated_at": "2018-04-03T13:37:24.479Z", "story_run_guid": "d59cd024-38b2-4287-b298-a8ee8dc86863", "previous_events_ids": [1785155927], "re_emitted": false } ``` #### List ## Description Retrieve a list of events. ## Request HTTP Method: **GET** | Parameter | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | since_id | **Optional** Only retrieve events after this ID. | | until_id | **Optional** Only retrieve events until (and including) this ID. | | since | **Optional** Only retrieve events created after this time (ISO 8601 timestamp). | | until | **Optional** Only retrieve events until this time (ISO 8601 timestamp). | | team_id | **Optional** Filter by the given team. | | story_id | **Optional** Filter by the given story. | | include_groups | **Optional** Include events from groups in the specified story. Only valid if `story_id` is specified. Boolean, defaults to `false`. | | show_reemitted_events_only | **Optional** Only retrieve events that have been re-emitted. Boolean, defaults to `false`. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 500. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/events \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing events in the Tines tenant. ### Field description | Parameter | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | id | Event ID. | | agent_id | ID of action that emitted the event. | | payload | JSON representation of the event payload. | | created_at | ISO 8601 Timestamp representing date and time the event was emitted. | | updated_at | ISO 8601 Timestamp representing date and time the event was last updated. Will always be the same as 'created_at'. | | story_run_guid | Unique identifier of that event's story run. | | previous_events_ids | IDs of the upstream action's events in that event's story run. | | re_emitted | Boolean flag indicating whether this event has been re-emitted. | ### Sample response ```json { "events": [ { "id": 1785421735, "user_id": 1, "agent_id": 21, "payload": { "propagation_webhook": { "username": "joe.bloggs", "age": 99 }, "delay_http_request": { "body": { "delay": "5" }, "headers": { "access-control-allow-credentials": "", "access-control-allow-headers": "", "access-control-allow-methods": "", "access-control-allow-origin": "", "access-control-expose-headers": "", "content-type": "application/json; charset=utf-8", "date": "Tue, 03 Apr 2018 13:37:24 GMT", "etag": "W/\"d-N6WkUL2Jgn7fCGyPWbbptw\"", "server": "nginx", "set-cookie": "sails.sid=s%3A6Hr22AAbEOurnGiqRo3; Path=/; HttpOnly", "vary": "Accept-Encoding", "content-length": "13", "connection": "Close" }, "status": 200 } }, "created_at": "2018-04-03T13:37:24.479Z", "updated_at": "2018-04-03T13:37:24.479Z", "story_run_guid": "d59cd024-38b2-4287-b298-a8ee8dc86863", "previous_events_ids": [1785155927], "re_emitted": false } ], "meta": { "current_page": "https:///api/v1/events?page=1&per_page=20", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Large payloads Please note that a response payload size exceeding 200MB will result in a 422 error. #### Re-emit ## Description Re‑emit an event. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ------------------------------- | | event_id | The ID of the event to re-emit. | ```bash curl -X POST \ https:///api/v1/events/<>/reemit \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Groups #### List run events ## Description Retrieve a list of events for a group run. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------------- | | group_id | The ID of the group. | | group_run_guid | The guid of the group run. | | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/groups/<>/runs/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON Array describing the events for a group run. ### Field description | Parameter | Description | | ------------ | -------------------------------------------------------------------- | | id | ID of the event. | | action_id | ID of action that emitted the event. | | created_at | ISO 8601 Timestamp representing date and time the event was emitted. | | is_reemitted | Boolean flag indicating whether this event has been re-emitted. | ### Sample response ```json { "group_run_events": [ { "id": 1126, "action_id": 3775, "created_at": "2023-12-13T16:19:50Z", "is_reemitted": false }, { "id": 1131, "action_id": 3809, "created_at": "2023-12-13T16:19:50Z", "is_reemitted": false } ], "meta": { "current_page": "https:///api/v1/groups/<>/runs/<>?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` #### List runs ## Description Retrieve a list of group runs. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------- | | group_id | The ID of the group. | | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/groups/<>/runs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON Array describing the group runs for a group. ### Field description | Parameter | Description | | ------------ | ---------------------------------------------- | | guid | Guid of the group run. | | duration | Duration of the group run. | | story_id | ID of the parent story. | | group_id | ID of the group. | | start_time | The time the group run started. | | end_time | The time the group run ended. | | action_count | Number of actions in the run. | | event_count | Number of events in the run. | | story_mode | The mode of the parent story `LIVE` or `TEST`. | | draft_id | ID of the draft to which the group belongs. | | draft_name | Name of the draft to which the group belongs. | ### Sample response ```json { "group_runs": [ { "guid": "5466f325-0bc6-47fb-943f-41d1a2a8d6ae", "duration": 0, "story_id": 155, "group_id": 200, "start_time": "2023-12-13T16:19:50Z", "end_time": "2023-12-13T16:19:50Z", "action_count": 5, "event_count": 5, "story_mode": "LIVE", "draft_id": 12345, "draft_name": "My draft" }, { "guid": "c0ea6684-1cfb-4ac5-858b-79c631daa79f", "duration": 0, "story_id": 155, "group_id": 200, "start_time": "2023-12-13T16:16:49Z", "end_time": "2023-12-13T16:16:49Z", "action_count": 1, "event_count": 1, "story_mode": "LIVE", "draft_id": 12345, "draft_name": "My draft" } ], "meta": { "current_page": "https:///api/v1/groups/<>/runs?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Links #### Delete ## Description Delete one or more links between actions. All links must belong to the same story. ## Request HTTP Method: **DELETE** | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------------- | | links | An array of link objects to delete. Each object must include `source_id` and `receiver_id`. | | source_id | The ID of the source action. | | receiver_id | The ID of the receiver action. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/links \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "links": [ { "source_id": "123", "receiver_id": "456" } ] }' ``` ### Bulk delete Multiple links can be deleted in a single request. All links must belong to the same story. ```bash curl -X DELETE \ https:///api/v1/links \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "links": [ { "source_id": "123", "receiver_id": "456" }, { "source_id": "456", "receiver_id": "789" } ] }' ``` ## Response A successful request will return an empty response with a `204` status code. ### Notes #### Create ## Description Create a note on the storyboard. Story or Group ID must be provided. Defaults to a draft called `test` if change control is enabled on the story and no draft_id is provided. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | story_id | **Optional** ID of story to which the note should be added. | | group_id | **Optional** ID of group to which the note should be added. | | content | The note [Markdown](https://www.markdownguide.org/basic-syntax/) formatted content. | | position | **Optional** An object describing the XY coordinates of the position on the story diagram. | | draft_id | **Optional** ID of the draft to which the note should be added. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ### Sample request ```bash curl -X POST \ https:///api/v1/notes/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "story_id": 813, "content": "# Header\n This is a list \n - item 1" }' ``` ## Response A successful request will return a JSON object describing the created note. ### Field description | Parameter | Description | | ---------- | ----------------------------------------------------------------------------------- | | id | The note ID. | | story_id | ID of story to which the note belongs. | | story_mode | Mode of the story to which the note belongs `LIVE` or `TEST` | | group_id | ID of group to which the note belongs. | | content | The note [Markdown](https://www.markdownguide.org/basic-syntax/) formatted content. | | position | An object describing the XY coordinates of the position on the story diagram. | | draft_id | ID of the draft to which the note belongs. | | draft_name | Name of the draft to which the note belongs. | ### Sample response ```json { "id": 21405, "story_id": 813, "story_mode": "LIVE", "group_id": null, "position": { "x": 0, "y": 0 }, "content": "# Header\n This is a list \n - item 1", "draft_id": 12345, "draft_name": "My draft" } ``` #### Get ## Description Retrieve a note. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------- | | note_id | The ID of the note to retrieve. | ```bash curl -X GET \ https:///api/v1/notes/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified note. ### Field description | Parameter | Description | | ---------- | ----------------------------------------------------------------------------------- | | id | The note ID. | | story_id | ID of story to which the note belongs. | | story_mode | Mode of the story to which the note belongs `LIVE` or `TEST` | | group_id | ID of group to which the note belongs. | | content | The note [Markdown](https://www.markdownguide.org/basic-syntax/) formatted content. | | position | An object describing the XY coordinates of the position on the story diagram. | ### Sample response ```json { "id": 21405, "story_id": 813, "story_mode": "LIVE", "group_id": null, "position": { "x": 0, "y": 0 }, "content": "# Header\n This is a list \n - item 1" } ``` #### Update ## Description Update a note. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------ | | content | **Optional** The note [Markdown](https://www.markdownguide.org/basic-syntax/) formatted content. | | position | **Optional** An object describing the XY coordinates of the position on the story diagram. | | Path Parameter | Description | | -------------- | -------------- | | note_id | ID of the note | ### Sample request ```bash curl -X PUT \ https:///api/v1/notes/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "content": "# Header\n This is a list \n - item 1\n - item 2", "position": { "x": 10, "y": 10 } }' ``` ## Response A successful request will return a JSON object describing the updated note. ### Field description | Parameter | Description | | ---------- | ----------------------------------------------------------------------------------- | | id | The note ID. | | story_id | ID of story to which the note belongs. | | story_mode | Mode of the story to which the note belongs `LIVE` or `TEST` | | group_id | ID of group to which the note belongs. | | content | The note [Markdown](https://www.markdownguide.org/basic-syntax/) formatted content. | | position | An object describing the XY coordinates of the position on the story diagram. | ### Sample response ```json { "id": 21405, "story_id": 813, "story_mode": "LIVE", "group_id": null, "position": { "x": 15, "y": 15 }, "content": "# Header\n This is a list \n - item 1\n - item 2" } ``` #### List ## Description List notes. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------ | | story_id | **Optional** List notes for the given story | | mode | **Optional** List notes for the given story mode (`LIVE` or `TEST`, must be used with `story_id`) | | team_id | **Optional** List notes for the given team | | group_id | **Optional** List notes for the given group | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | draft_id | **Optional** List notes for the given draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ```bash curl -X GET \ https:///api/v1/notes/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an array listing the requested notes. ### Field description | Parameter | Description | | ---------- | ----------------------------------------------------------------------------------- | | id | The note ID. | | story_id | ID of story to which the note belongs. | | story_mode | Mode of the story to which the note belongs `LIVE` or `TEST` | | group_id | ID of group to which the note belongs. | | content | The note [Markdown](https://www.markdownguide.org/basic-syntax/) formatted content. | | position | An object describing the XY coordinates of the position on the story diagram. | | draft_id | ID of the draft to which the note belongs. | | draft_name | Name of the draft to which the note belongs. | ### Sample response ```json { "annotations": [ { "id": 21405, "story_id": 813, "story_mode": "LIVE", "group_id": null, "position": { "x": 0, "y": 0 }, "content": "# Example note", "draft_id": 12345, "draft_name": "My draft" } ], "meta": { "current_page": "https:///api/v1/notes?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete ## Description Delete a note. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ----------------------------- | | note_id | The ID of the note to delete. | ```bash curl -X DELETE \ https:///api/v1/notes/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Owners #### Create ## Description Create a story owner for a story. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------- | | story_id | ID of the story in which the story owner should be created. | | user_id | The ID of the user that should be added as a story owner. The user must be a member of the team in which the story exists. | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/owners \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"user_id":"<>"}' ``` ## Response A successful request will return a JSON object describing the story in which the owner was created. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | ### Sample response ```json { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ] } ``` #### Delete ## Description Delete a story owner for a story. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ----------------------------------------------------------------------------------------------------- | | story_id | The ID of the story in which the story owner should be deleted. | | user_id | The ID of the user that should be removed as a story owner. The user must be an existing story owner. | ```bash curl -X DELETE \ https:///api/v1/stories/<>/owners \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "user_id": <> }' ``` ## Response A successful request will return an empty response with a `204` status code. ### Recipients #### Create ## Description Create a story recipient for a story. The recipients will receive story monitoring communications when enabled. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | story_id | ID of the story in which the story recipient should be created. | | address | The email or webhook URL that should receive story monitoring communications. | | draft_id | **Optional** The ID of the draft to update. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/recipients \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "address": "alice@example.com" }' ``` ## Response A successful request will return a JSON object describing the story in which the recipient was created. ### Field description | Parameter | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The story name. | | user_id | ID of story creator. | | description | A user-defined description of the story. | | keep_events_for | Defined event retention period in seconds. | | disabled | Boolean flag indicating whether story is disabled. | | priority | Boolean flag indicating whether story is high priority story. | | send_to_story_enabled | Boolean flag indicating if Send to Story is enabled. | | send_to_story_access_source | `STS`, `STS_AND_WORKBENCH`, `WORKBENCH` or `OFF` indicating where the send to story can be used. | | send_to_story_access | Controls who is allowed to send to this story (`TEAM`,`GLOBAL`,`SPECIFIC_TEAMS`). | | send_to_story_referring_story_ids | List of story ids that call this Send to Story enabled story. Only present when `send_to_story_enabled` is `true`. | | shared_team_slugs | List of teams' slugs that can send to this story when `send_to_story_access` is `SPECIFIC_TEAMS`, otherwise empty. | | send_to_story_skill_use_requires_confirmation | Boolean flag indicating whether workbench should ask for confirmation before running this story. | | entry_agent_id | The ID of the entry action for this story. | | exit_agents | An Array of objects describing exit actions for this story. | | team_id | ID of team to which the story belongs. | | tags | An array of tags used to classify the story. | | guid | Unique identifier of the story. | | slug | An underscored representation of the story name. | | created_at | ISO 8601 Timestamp representing date and time the story was created. | | updated_at | ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself. | | edited_at | ISO 8601 Timestamp representing date and time the story was last logically updated. | | mode | The mode of the story. `LIVE` or `TEST` | | id | The story ID. | | folder_id | ID of folder to which the story belongs. | | published | Boolean flag indicating whether the story is published. | | change_control_enabled | Boolean flag indicating if change control is enabled. | | locked | Boolean flag indicating whether the story is locked to changes. | | owners | List of user IDs that are listed as owners on the story. | | monitor_failures | Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled. | | actions_with_monitoring | List of action IDs with monitoring enabled. | | recipients | List of monitoring recipients for the story. | ### Sample response ```json { "name": "Simple story", "user_id": 167, "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant", "keep_events_for": 604800, "disabled": false, "priority": false, "send_to_story_enabled": false, "send_to_story_access_source": "OFF", "send_to_story_access": null, "send_to_story_skill_use_requires_confirmation": true, "shared_team_slugs": [], "entry_agent_id": null, "exit_agents": [], "team_id": 1, "tags": ["Tag 1", "Tag 2"], "guid": "df1e838a18d20696120b41516497b017", "slug": "simple_story", "created_at": "2021-05-10T08:56:50Z", "updated_at": "2021-05-10T08:56:50Z", "edited_at": "2021-05-10T08:56:50Z", "mode": "LIVE", "id": 7981, "folder_id": 1, "published": true, "change_control_enabled": false, "locked": false, "owners": [1], "monitor_failures": false, "actions_with_monitoring": [], "recipients": [ { "address": "test@example.com" } ] } ``` #### Delete ## Description Delete a story recipient for a story. The recipient will no longer receive story monitoring communications and will be removed from the recipients list. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------- | | story_id | The ID of the story in which the story recipient should be deleted. | | address | The email or webhook URL that should no longer receive story monitoring communications. | | draft_id | **Optional** The ID of the draft to update. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ### Sample request ```bash curl -X DELETE \ https:///api/v1/stories/<>/recipients \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "address": "alice@example.com" }' ``` ## Response A successful request will return an empty response with a `204` status code. ### Story runs #### List run events ## Description Retrieve a list of events for a story run. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------------- | | story_id | The ID of the story. | | story_run_guid | The guid of the story run. | | Query Parameter | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | story_mode | **Optional** The mode of the story. | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | draft_id | **Optional** Return events for a specific draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ```bash curl -X GET \ https:///api/v1/stories/<>/runs/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON Array describing the events for a story run. ### Field description | Parameter | Description | | ------------ | -------------------------------------------------------------------- | | id | ID of the event. | | action_id | ID of action that emitted the event. | | created_at | ISO 8601 Timestamp representing date and time the event was emitted. | | is_reemitted | Boolean flag indicating whether this event has been re-emitted. | ### Sample response ```json { "story_run_events": [ { "id": 1126, "action_id": 3775, "created_at": "2023-12-13T16:19:50Z", "is_reemitted": false }, { "id": 1131, "action_id": 3809, "created_at": "2023-12-13T16:19:50Z", "is_reemitted": false } ], "meta": { "current_page": "https:///api/v1/stories/<>/runs/<>?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` #### List runs ## Description Retrieve a list of story runs. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | | Query Parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | story_mode | **Optional** The mode of the story. | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | draft_id | **Optional** Return runs for a specific draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | since | **Optional** Only retrieve story runs that started after this time (ISO 8601 timestamp). | | until | **Optional** Only retrieve story runs that started until this time (ISO 8601 timestamp). | ```bash curl -X GET \ https:///api/v1/stories/<>/runs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON Array describing the story runs for a story. ### Field description | Parameter | Description | | ------------ | --------------------------------------- | | guid | Guid of the story run. | | duration | Duration of the story run. | | story_id | ID of the story. | | start_time | The time the story run started. | | end_time | The time the story run ended. | | action_count | Number of actions in the run. | | event_count | Number of events in the run. | | story_mode | The mode of the story `LIVE` or `TEST`. | | draft_id | ID of the selected draft. | | draft_name | Name of the selected draft. | ### Sample response ```json { "story_runs": [ { "guid": "5466f325-0bc6-47fb-943f-41d1a2a8d6ae", "duration": 0, "story_id": 155, "start_time": "2023-12-13T16:19:50Z", "end_time": "2023-12-13T16:19:50Z", "action_count": 5, "event_count": 5, "story_mode": "LIVE", "draft_id": "1234", "draft_name": "Initial Draft" }, { "guid": "c0ea6684-1cfb-4ac5-858b-79c631daa79f", "duration": 0, "story_id": 155, "start_time": "2023-12-13T16:16:49Z", "end_time": "2023-12-13T16:16:49Z", "action_count": 1, "event_count": 1, "story_mode": "LIVE", "draft_id": "1234", "draft_name": "Initial Draft" } ], "meta": { "current_page": "https:///api/v1/stories/<>/runs?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Story versions #### Create ## Description Create a story version. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | name | **Optional** The story version name. | | draft_id | **Optional** Specify the draft for which to create a version. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | ### Sample request ```bash curl -X POST \ https:///api/v1/stories/<>/versions \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Test story version" }' ``` ## Response A successful request will return a JSON object describing the story version. ### Field description | Parameter | Description | | ----------- | --------------------------------------- | | id | The story version ID. | | name | The story version name. | | description | The story description. | | timestamp | The time the story version was created. | ### Sample response ```json { "id": 885, "name": "API created version", "description": "", "timestamp": "2023-11-13T11:16:05Z" } ``` #### Get ## Description Retrieve a story version. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ---------------------------------------- | | story_id | The ID of the story. | | version_id | The ID of the story version to retrieve. | ```bash curl -X GET \ https:///api/v1/stories/<>/versions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON object describing the story version. ### Field description | Parameter | Description | | ----------- | --------------------------------------- | | id | story version id. | | name | story version name. | | description | story version description. | | timestamp | The time the story version was created. | | export_file | The export file for the story version. | ### Sample response ```json { "id": 889, "name": "Story version 1", "description": "", "timestamp": "2023-11-13T11:16:05Z", "export_file": { "schema_version": 18, "standard_lib_version": 38, "action_runtime_version": 4, "name": "Story 7", "description": "Example export for an empty story", "guid": "a177fea37b6ffd9d52fb4b27e635dbb6", "slug": "story_7", "agents": [], "diagram_notes": [], "links": [], "diagram_layout": "{}", "send_to_story_enabled": false, "entry_agent_guid": null, "exit_agent_guids": [], "exit_agent_guid": null, "api_entry_action_guids": [], "api_exit_action_guids": [], "keep_events_for": 604800, "reporting_status": true, "send_to_story_access": null, "story_library_metadata": {}, "monitor_failures": false, "form": null, "synchronous_webhooks_enabled": false, "forms": [], "pages": [], "tags": [], "time_saved_unit": "minutes", "time_saved_value": 0, "origin_story_identifier": "cloud:93b6b6f3c7c8d824afc9cb6d0b32454c:a177fea37b6ffd9d52fb4b27e635dbb6", "integration_product": null, "integration_vendor": null, "exported_at": "2023-11-13T11:25:48Z", "icon": ":clipboard:", "integrations": [] } } ``` #### Update ## Description Update a story version. ## Request HTTP Method: **POST** | Query Parameter | Description | | --------------- | ----------------------------------- | | name | The new name for the story version. | | Path Parameter | Description | | -------------- | -------------------------------------- | | story_id | The ID of the story. | | version_id | The ID of the story version to update. | ```bash curl -X POST \ https:///api/v1/stories/<>/versions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated version name" }' ``` ## Response A successful request will return the JSON object describing the updated story version. ### Field description | Parameter | Description | | ----------- | --------------------------------------- | | id | story version id. | | name | story version name. | | description | story version description. | | timestamp | The time the story version was created. | ### Sample response ```json { "id": 889, "name": "Updated version name", "description": "", "timestamp": "2023-11-13T11:16:05Z" } ``` #### List ## Description Retrieve a list of story versions. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------- | | story_id | The ID of the story. | | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | draft_id | **Optional** The ID of the draft. [About drafts](https://www.tines.com/docs/stories/change-control/#api-endpoints). | ```bash curl -X GET \ https:///api/v1/stories/<>/versions \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON Array describing the story versions for a story. ### Field description | Parameter | Description | | ----------- | --------------------------------------- | | id | story version id. | | name | story version name. | | description | story version description. | | timestamp | The time the story version was created. | ### Sample response ```json { "story_versions": [ { "id": 889, "name": "Story version 1", "description": "", "timestamp": "2023-11-13T11:16:05Z" } ], "meta": { "current_page": "https:///api/v1/stories/<>/versions?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 7 } } ``` #### Delete ## Description Delete a story version. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | -------------------------------------- | | story_id | The ID of the story. | | version_id | The ID of the story version to delete. | ```bash curl -X DELETE \ https:///api/v1/stories/<>/versions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the JSON object describing the deleted story version with a `200` status code. ### Field description | Parameter | Description | | ------------ | ----------------- | | destroyed_id | story version ID. | ### Sample response ```json { "destroyed_id": 1 } ``` ## Teams ### Create ## Description Create a team in Tines. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | -------------- | | name | The team name. | ### Sample request ```bash curl -X POST \ https:///api/v1/teams/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "Security team" }' ``` ## Response A successful request will return a JSON object describing the created team ### Field description | Parameter | Description | | --------- | -------------- | | id | The team ID. | | name | The team name. | ### Sample response ```json { "id": 1, "name": "Security team" } ``` ### Get ## Description Retrieve a single team or case group. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------- | | team_id | The ID of the team to retrieve. | ```bash curl -X GET \ https:///api/v1/teams/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified team. ### Field description | Parameter | Description | | --------- | ---------------- | | id | The team ID. | | name | The team name. | | groups | The team groups. | ### Sample response ```json { "id": 1, "name": "Security team", "groups": [ { "id": 3, "name": "Tier 1" } ] } ``` ### Update ## Description Update a team. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | -------------------------- | | name | The new name for the team. | | Path Parameter | Description | | -------------- | -------------- | | team_id | ID of the team | ### Sample request ```bash curl -X PUT \ https:///api/v1/teams/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "Security team 1" }' ``` ## Response A successful request will return a JSON object describing the updated team ### Field description | Parameter | Description | | --------- | -------------- | | id | The team ID. | | name | The team name. | ### Sample response ```json { "id": 1, "name": "Security team 1" } ``` ### List ## Description Retrieve a list of teams. ## Request HTTP Method: **GET** | Query Parameter | Description | | ---------------------- | --------------------------------------------------------------------------------------------------- | | include_personal_teams | **Optional** Include personal teams in the response Default: `false` | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/teams \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing teams in the Tines tenant. ### Field description | Parameter | Description | | --------- | ---------------- | | id | The team ID. | | name | The team name. | | groups | The team groups. | ### Sample response ```json { "teams": [ { "id": 1, "name": "Security Team", "groups": [ { "id": 3, "name": "Tier 1" } ] }, { "id": 2, "name": "Engineering Team", "groups": [] } ], "meta": { "current_page": "https:///api/v1/teams?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### List members ## Description Retrieve a list of team members. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------- | | team_id | ID of the team | | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/teams/<>/members \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing team members. ### Field description | Parameter | Description | | ------------------- | ----------------------------------------------------------------------------- | | id | User ID. | | email | User email. | | first_name | User first name. | | last_name | User last name. | | is_admin | Boolean flag indicating whether user is an admin. | | created_at | Timestamp describing when the user was created. | | last_seen | Timestamp describing when the user was last seen in the platform. | | invitation_accepted | Boolean flag indicating if the user accepted the invitation to join the team. | | role | The user’s role on the team. | ### Sample response ```json { "members": [ { "id": 1, "first_name": "First name", "last_name": "Last name", "email": "user@example.com", "is_admin": true, "created_at": "2021-03-11T09:00:58Z", "last_seen": "2021-04-30T08:56:05Z", "invitation_accepted": true, "role": "TEAM_ADMIN" } ], "meta": { "current_page": "https:///api/v1/teams/4178/members?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Remove member ## Description Remove a user from a team ## Request HTTP Method: **POST** | Path Parameter | Description | | -------------- | -------------- | | team_id | ID of the team | | Query Parameter | Description | | --------------- | -------------- | | user_id | ID of the user | ```bash curl -X POST \ https:///api/v1/teams/<>/remove_member \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "user_id": 2 }' ``` ## Response A successful request will return a 200 response ### Sample response ```json { "deleted_id": 2 } ``` ### Delete ## Description Delete a team or case group. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ----------------------------- | | team_id | The ID of the team to delete. | ```bash curl -X DELETE \ https:///api/v1/teams/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Invite member ## Description Invite a user to join a team ## Request HTTP Method: **POST** | Path Parameter | Description | | -------------- | -------------- | | team_id | ID of the team | | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | email | Email address of the user | | user_id | **optional** ID of an existing user in the Tines tenant | | role | **optional** Which [role](https://www.tines.com/docs/admin/teams#team-roles) the user should have on the team. Supports both default and custom roles. | **`user_id` or `email` must be provided but not both.** ```bash curl -X POST \ https:///api/v1/teams/<>/invite_member \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "email": "user@example.com" }' ``` ## Response A successful request will return a JSON object representing the invited user. ### Field description | Parameter | Description | | ------------------- | ----------------------------------------------------------------------------- | | id | User ID. | | email | User email. | | first_name | User first name. | | last_name | User last name. | | is_admin | Boolean flag indicating whether user is an admin. | | created_at | Timestamp describing when the user was created. | | last_seen | Timestamp describing when the user was last seen in the platform. | | invitation_accepted | Boolean flag indicating if the user accepted the invitation to join the team. | | role | The user’s role on the team. | ### Sample response ```json { "id": 2, "first_name": "First name", "last_name": "Last name", "email": "user@example.com", "is_admin": false, "created_at": "2021-04-30T09:12:40Z", "last_seen": null, "invitation_accepted": false, "role": "VIEWER" } ``` ### Resend member invitation ## Description Resend a team invitation to a user. ## Request HTTP Method: **POST** | Path Parameter | Description | | -------------- | -------------- | | team_id | ID of the team | | Query Parameter | Description | | --------------- | ----------- | | user_id | ID of user | ```bash curl -X POST \ https:///api/v1/teams/<>/resend_invitation \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "user_id": 2 }' ``` ## Response A successful request will return a JSON object representing the invited user. ### Field description | Parameter | Description | | ------------------- | ---------------------------------------------------------------------------- | | id | User ID. | | email | User email. | | first_name | User first name. | | last_name | User last name. | | is_admin | Boolean flag indicating whether user is an admin. | | created_at | Timestamp describing when the user was created. | | last_seen | Timestamp describing when the user was last seen in the platform. | | invitation_accepted | Boolean flag indicating if the user accepted the invitation to join the team | ### Sample response ```json { "id": 2, "first_name": "First name", "last_name": "Last name", "email": "user@example.com", "is_admin": false, "created_at": "2021-04-30T09:12:40Z", "last_seen": null, "invitation_accepted": false } ``` ### Destroy static external ID ## Description Destroy a team static external ID in Tines. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ------------ | | team_id | The team ID. | ### Sample request ```bash curl -X POST \ https:///api/v1/teams/<>/destroy_static_external_id \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a 200 response and the ID of the destroyed team static external ID. ```bash 12 ``` ## Cases ### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Create a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | The team ID the case is within. | | name | The case name. | | description | **Optional** The case description. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | priority | **Optional** The case priority - critical, high, medium, low or info. | | status | **Optional** The case status - open or closed. | | author_email | **Optional** The email of the user creating the cases. | | assignee_emails | **Optional** An array of user email addresses to assign to the case. Case will automatically be assigned to the user associated with the API token if none provided. | | tag_names | **Optional** An array of tag names. | | record_ids | **Optional** An array of record IDs to add to the case. | | opened_at | **Optional** ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | **Optional** ISO 8601 Timestamp representing the date and time the case was resolved at. | | metadata | **Optional** Case related metadata represented as key-value pairs. | | team_case_buttons | **Optional** An array of team case buttons for downstream actions associated with the case. | | closure_conditions | **Optional** An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "team_id": "team_id", "name": "Suspicious login detected", "priority": "high", "description": "This is a high priority case created via the API", "assignee_emails": [ "jane@tines.io" ], "tag_names": [ "login", "security" ], "record_ids": [ "record_id" ], "metadata": { "key": "value" }, "team_case_buttons": [ { "button_type": "page", "url": "https://tenant.tines.com/pages/55e94b9b4e26175051c0287f4259363f/", "label": "Isolate host and give reason", "button_text": "Open form" }, { "button_type": "webhook", "url": "http://tenant.tines.com/webhook/e840b4e8cf60437196d9a4bcb85d2de0/61441bc05fddfa4c09924b23fcf72b91", "label": "Isolate host", "button_text": "Isolate" } ], "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ] }' ``` ## Response A successful request will return a JSON object describing the created case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------ | | case_id | The case ID. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | team_case_actions | An array of team case actions taken within the case. | | team | The team the case is within - ID & name. | | team_case_buttons | An array of team case buttons for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case (IDs only). | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements for the case. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "description": "This is a high priority case created via the API", "status": "OPEN", "url": "https://tenant.tines.com/team/2/cases/42", "metadata": {}, "author": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "opened_by": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "resolved_by": null, "assignees": [ { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false } ], "tags": [ { "id": 4, "name": "login" } ], "team_case_actions": [ { "id": 7508, "action": "CREATED", "value": "42", "user": {} } ], "team": { "id": 2, "name": "Team 1" }, "team_case_buttons": [ { "id": 8, "button_type": "webhook", "url": "http://tenant.tines.com/webhook/e840b4e8cf60437196d9a4bcb85d2de0/61441bc05fddfa4c09924b23fcf72b91", "label": "Isolate host", "button_text": "Isolate" }, { "id": 9, "button_type": "page", "url": "https://tenant.tines.com/pages/55e94b9b4e26175051c0287f4259363f/", "label": "Isolate host and submit reason", "button_text": "Open form" } ], "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ] "linked_cases": [], "opened_at": "2023-12-18T22:29:22Z", "resolved_at": null, "created_at": "2023-12-18T22:29:22Z", "updated_at": "2023-12-18T22:29:22Z", "records": [ { "id": 187, "results": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ] } ], "priority": "HIGH" } ``` ### Create ## Description Create a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | The team ID the case is within. | | name | The case name. | | description | **Optional** The case description. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | priority | **Optional** The case priority - critical, high, medium, low or info. | | status | **Optional** The case status - open or closed. | | sub_status_id | **Optional** The case sub-status ID. | | author_email | **Optional** The email of the user creating the cases. | | assignee_emails | **Optional** An array of user email addresses to assign to the case. Case will automatically be assigned to the user associated with the API token if none provided. | | tag_names | **Optional** An array of tag names. | | opened_at | **Optional** ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | **Optional** ISO 8601 Timestamp representing the date and time the case was resolved at. | | metadata | **Optional** Case related metadata represented as key-value pairs. | | closure_conditions | **Optional** An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case.

**N.B.** The formula key should be passed as a raw formula wrapped in strings as opposed to a pill value. | | field_values | **Optional** An object containing a key-value pair of case input IDs and values for the case. Case input IDs provided must exist within the team for the field to be successfully added to the case. | | tasks | **Optional** An array of task objects to create with the case. Each task object should contain a description and optionally assignee_ids or assignee_emails. | | blocks | **Optional** An array of block objects to create with the case. See [block parameters](#block-parameters) below. | ### Block parameters Each object in the `blocks` array accepts: | Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | | title | The title of the block. | | block_type | The type of block to create - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | elements | An array of elements to add to the block. Required but may be empty for block types that do not support elements. | | hidden | **Optional** A boolean (true or false). | | guid | **Optional** A client-generated identifier for the block, used for referencing in `parent_block_guid`. | | parent_block_guid | **Optional** The `guid` of a block_group block within the same request to nest this block inside. | #### Note element parameters | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | **Optional** The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File element parameters | Parameter | Description | | ------------- | ---------------------------------------------- | | filename | The name of the file. | | file_contents | The base64-encoded contents of the file. | | annotation | **Optional** The annotation text for the file. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "team_id": "team_id", "name": "Suspicious login detected", "priority": "high", "description": "This is a high priority case created via the API", "assignee_emails": [ "jane@tines.io" ], "tag_names": [ "login", "security" ], "metadata": { "key": "value" }, "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ], "field_values": { "1": "Windows" }, "tasks": [ { "description": "Review security logs", "assignee_ids": [123, 456] }, { "description": "Contact affected users" } ], "blocks": [ { "title": "Investigation notes", "block_type": "note", "elements": [ { "content": "Initial triage completed - suspicious IP identified.", "note_type": "text", "color": "gold" } ] }, { "title": "Evidence", "block_type": "block_group", "guid": "evidence-group", "elements": [] }, { "title": "Log files", "block_type": "file", "parent_block_guid": "evidence-group", "elements": [ { "filename": "auth-logs.txt", "file_contents": "SGVsbG8gV29ybGQ=" } ] } ] }' ``` ## Response A successful request will return a JSON object describing the created case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | sub_status | An object describing the case sub-status. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | activities | An array of team case actions taken within the case. | | activities_meta | Metadata defining pagination params required to fetch additional activities for the case. | | team | The team the case is within - ID & name. | | actions | An array of case actions for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case - ID & name. | | sla | An object describing the case SLA status. Times are in seconds. | | slas | An array of SLAs for the case. Times are in seconds. | | fields | An array of field values for the case. | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case, grouped by record type. | | records_meta | Metadata defining pagination params required to fetch additional records for the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | | blocks | An array of block objects specifying the block title, slug, type, position, visibility, group, and element ids. | | tasks | An array of tasks associated with the case. | ### Sample response ```json { "case_id": 1, "name": "Case 1..25", "description": null, "status": "OPEN", "sub_status": { "id": 1, "name": "To do" }, "priority": "LOW", "url": "http:///team/276/cases/1", "metadata": { "foo": "bar" }, "author": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "opened_by": null, "resolved_by": null, "assignees": [ { "user_id": "176", "first_name": "Example", "last_name": "Person", "email": "person_10@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "178", "first_name": "Example", "last_name": "Person", "email": "person_12@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "180", "first_name": "Example", "last_name": "Person", "email": "person_14@example.com", "avatar_url": "", "is_service_account": false } ], "tags": [ { "id": 7, "name": "Tag 1" }, { "id": 8, "name": "Tag 2" }, { "id": 9, "name": "Tag 3" } ], "sla": { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, "slas": [ { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 100, "exceeded": true, "sla_type": "response" } ], "fields": [ { "id": 1, "value": "Windows 11", "case_input": { "id": 1, "key": "operating_system", "name": "Operating system", "validation_type": "none", "validation_options": {} } } ], "activities": [ { "id": 109, "activity_type": "CREATED", "value": "115", "user": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 111, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "170", "first_name": "Example", "last_name": "Person", "email": "person_4@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 113, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "172", "first_name": "Example", "last_name": "Person", "email": "person_6@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" } ], "team": { "id": 276, "name": "Test team 1" }, "linked_cases": [{ "case_id": 1, "name": "Case 1" }], "closure_conditions": [ { "formula": "=SIZE(team_case.assignees) > 2", "name": "Number of assignees" } ], "opened_at": "2024-03-25T15:40:39Z", "resolved_at": null, "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z", "records": [ { "record_type_id": 55, "record_type_name": "Record type 2", "record_type_record_results": [ { "id": 59, "results": [ { "id": 59110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 59109, "name": "Story name", "value": "Alert investigation" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 58, "results": [ { "id": 58110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 58109, "name": "Story name", "value": "Alert investigation #1" } ], "created_at": "2024-04-16T08:02:03Z" } ] }, { "record_type_id": 54, "record_type_name": "Record type 1", "record_type_record_results": [ { "id": 56, "results": [ { "id": 56108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 56107, "name": "Story name", "value": "Alert investigation #2" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 55, "results": [ { "id": 55108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 55107, "name": "Story name", "value": "Alert investigation #3" } ], "created_at": "2024-04-16T08:02:03Z" } ] } ], "actions": [ { "id": 7, "url": "http://example.com", "label": "Hello, world!", "action_type": "page" } ], "blocks": [ { "id": 1, "title": "Notes", "slug": "blk_notes", "block_type": "note", "position": 1, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 54, "id": 54 }, { "element_id": 674, "id": 674 }, { "element_id": 524, "id": 524 } ] }, { "id": 3, "title": "Investigation", "slug": "blk_investigation", "block_type": "block_group", "position": 2, "hidden": false, "block_group_id": null, "elements": [] }, { "id": 2, "title": "Additional notes", "slug": "blk_additional_notes", "block_type": "note", "position": 3, "hidden": true, "block_group_id": 3, "elements": [ { "element_id": 235, "id": 235 }, { "element_id": 342, "id": 342 }, { "element_id": 744, "id": 744 } ] } ], "tasks": [ { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123" }, { "id": "456" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Contact affected users", "completed": false, "assignees": [], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } ], "activities_meta": { "current_page": "https:///api/v2/cases/1/activities?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 }, "records_meta": { "current_page": "https:///api/v2/cases/1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Get | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a single case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------- | | case_id | The ID of the case to retrieve. | ```bash curl -X GET \ https:///api/v1/cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The case ID. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | team_case_actions | An array of team case actions taken within the case. | | team | The team the case is within - ID & name. | | team_case_buttons | An array of team case buttons for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case (IDs only). | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "description": "This is a high priority case created via the API", "status": "OPEN", "url": "https://tenant.tines.com/team/2/cases/42", "metadata": {}, "author": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "opened_by": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "resolved_by": null, "assignees": [ { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false } ], "tags": [ { "id": 4, "name": "login" } ], "team_case_actions": [ { "id": 7508, "action": "CREATED", "value": "42", "user": {} } ], "team": { "id": 2, "name": "Team 1" }, "team_case_buttons": [ { "id": 8, "button_type": "webhook", "url": "http://tenant.tines.com/webhook/e840b4e8cf60437196d9a4bcb85d2de0/61441bc05fddfa4c09924b23fcf72b91", "label": "Isolate host", "button_text": "Isolate" }, { "id": 9, "button_type": "page", "url": "https://tenant.tines.com/pages/55e94b9b4e26175051c0287f4259363f/", "label": "Isolate host and submit reason", "button_text": "Open form" } ], "linked_cases": [], "opened_at": "2023-12-18T22:29:22Z", "resolved_at": null, "created_at": "2023-12-18T22:29:22Z", "updated_at": "2023-12-18T22:29:22Z", "records": [ { "id": 187, "results": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ] } ], "priority": "HIGH", "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ] } ``` ### Get ## Description Retrieve a single case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------- | | case_id | The ID of the case to retrieve. | ```bash curl -X GET \ https:///api/v2/cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | sub_status | An object describing the case sub-status. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | activities | An array of team case actions taken within the case. | | activities_meta | Metadata defining pagination params required to fetch additional activities for the case. | | team | The team the case is within - ID & name. | | actions | An array of case actions for downstream actions associated with the case. | | fields | An array of field values for the case. | | linked_cases | An array of cases linked to this case - ID & name. | | sla | An object describing the case SLA status. Times are in seconds. | | slas | An an array of SLAs for the case. Times are in seconds. | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case, grouped by record type. | | records_meta | Metadata defining pagination params required to fetch additional records for the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | | blocks | An array of block objects specifying the block title, slug, type, position, visibility, group, and element ids. | | tasks | An array of tasks associated with the case. | #### Task object fields | Parameter | Description | | ----------- | -------------------------------------------------------------------------- | | id | The task ID. | | description | The task description. | | completed | Boolean indicating whether the task is completed. | | assignees | An array of users assigned to the task. | | created_at | ISO 8601 Timestamp representing the date and time the task was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the task was updated at. | #### Task assignee object fields | Parameter | Description | | ---------- | ---------------------- | | id | The user ID. | | email | The user email. | | first_name | The user's first name. | | last_name | The user's last name. | ### Sample response ```json { "case_id": 1, "name": "Case 1..25", "description": null, "status": "OPEN", "sub_status": { "id": 1, "name": "To do" }, "priority": "LOW", "url": "http:///team/276/cases/1", "metadata": { "foo": "bar" }, "author": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "opened_by": null, "resolved_by": null, "assignees": [ { "user_id": "176", "first_name": "Example", "last_name": "Person", "email": "person_10@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "178", "first_name": "Example", "last_name": "Person", "email": "person_12@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "180", "first_name": "Example", "last_name": "Person", "email": "person_14@example.com", "avatar_url": "", "is_service_account": false } ], "tags": [ { "id": 7, "name": "Tag 1" }, { "id": 8, "name": "Tag 2" }, { "id": 9, "name": "Tag 3" } ], "sla": { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, "slas": [ { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 100, "exceeded": true, "sla_type": "response" } ], "fields": [ { "id": 1, "value": "Windows 11", "case_input": { "id": 1, "key": "operating_system", "name": "Operating system", "validation_type": "none", "validation_options": {} } } ], "activities": [ { "id": 109, "activity_type": "CREATED", "value": "115", "user": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 111, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "170", "first_name": "Example", "last_name": "Person", "email": "person_4@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 113, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "172", "first_name": "Example", "last_name": "Person", "email": "person_6@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" } ], "team": { "id": 276, "name": "Test team 1" }, "linked_cases": [{ "case_id": 1, "name": "Case 1" }], "closure_conditions": [ { "formula": "=SIZE(team_case.assignees) > 2", "name": "Number of assignees" } ], "opened_at": "2024-03-25T15:40:39Z", "resolved_at": null, "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z", "records": [ { "record_type_id": 55, "record_type_name": "Record type 2", "record_type_record_results": [ { "id": 59, "results": [ { "id": 59110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 59109, "name": "Story name", "value": "Alert investigation" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 58, "results": [ { "id": 58110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 58109, "name": "Story name", "value": "Alert investigation #1" } ], "created_at": "2024-04-16T08:02:03Z" } ] }, { "record_type_id": 54, "record_type_name": "Record type 1", "record_type_record_results": [ { "id": 56, "results": [ { "id": 56108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 56107, "name": "Story name", "value": "Alert investigation #2" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 55, "results": [ { "id": 55108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 55107, "name": "Story name", "value": "Alert investigation #3" } ], "created_at": "2024-04-16T08:02:03Z" } ] } ], "actions": [ { "id": 7, "url": "http://example.com", "label": "Hello, world!", "action_type": "page" } ], "blocks": [ { "id": 1, "title": "Notes", "slug": "blk_notes", "block_type": "note", "position": 1, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 54, "id": 54 }, { "element_id": 674, "id": 674 }, { "element_id": 524, "id": 524 } ] }, { "id": 2, "title": "Additional notes", "slug": "blk_additional_notes", "block_type": "note", "position": 2, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 235, "id": 235 }, { "element_id": 342, "id": 342 }, { "element_id": 744, "id": 744 } ] } ], "tasks": [ { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123", "email": "user1@example.com", "first_name": "John", "last_name": "Doe" }, { "id": "456", "email": "user2@example.com", "first_name": "Jane", "last_name": "Smith" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Contact affected users", "completed": true, "assignees": [ { "id": "789", "email": "user3@example.com", "first_name": "Bob", "last_name": "Johnson" } ], "created_at": "2024-03-25T15:30:20Z", "updated_at": "2024-03-25T16:15:45Z" } ], "activities_meta": { "current_page": "https:///api/v2/cases/1/activities?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 }, "records_meta": { "current_page": "https:///api/v2/cases/1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Update | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Update a case. ## Request HTTP Method: **PUT** | Parameter | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | name | **Optional** The case name. | | description | **Optional** The case description. | | priority | **Optional** The case priority - critical, high, medium, low or info. | | status | **Optional** The case status - open or closed. A case re-opened email will be sent to case assignees upon reopening a case. | | add_assignee_emails | **Optional** An array of user email addresses to assign to the case. | | remove_assignee_emails | **Optional** An array of user email addresses to remove from the case. | | add_tag_names | **Optional** An array of tag names to add to the case. | | remove_tag_names | **Optional** An array of tag names to remove from the case. | | add_record_ids | **Optional** An array of record IDs to add to the case. | | remove_record_ids | **Optional** An array of record IDs to remove from the case. | | author_email | **Optional** The email of the user updating the case. | | opened_at | **Optional** ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | **Optional** ISO 8601 Timestamp representing the date and time the case was resolved at. | | metadata | **Optional** Case related metadata represented as key-value pairs. | | team_case_buttons | **Optional** An array of team case buttons for downstream actions associated with the case. | | closure_conditions | **Optional** An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X PUT \ https:///api/v1/cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated case name" }' ``` ## Response A successful request will return a JSON object describing the updated case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The case ID. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | team_case_actions | An array of team case actions taken within the case. | | team | The team the case is within - ID & name. | | team_case_buttons | An array of team case buttons for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case (IDs only). | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | ### Sample response ```json { "case_id": 42, "name": "Updated case name", "description": "This is a high priority case created via the API", "status": "OPEN", "url": "https://tenant.tines.com/team/2/cases/42", "metadata": {}, "author": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "opened_by": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "resolved_by": null, "assignees": [ { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false } ], "tags": [ { "id": 4, "name": "login" } ], "team_case_actions": [ { "id": 7508, "action": "CREATED", "value": "42", "user": {} } ], "team": { "id": 2, "name": "Team 1" }, "team_case_buttons": [ { "id": 8, "button_type": "webhook", "url": "http://tenant.tines.com/webhook/e840b4e8cf60437196d9a4bcb85d2de0/61441bc05fddfa4c09924b23fcf72b91", "label": "Isolate host", "button_text": "Isolate" }, { "id": 9, "button_type": "page", "url": "https://tenant.tines.com/pages/55e94b9b4e26175051c0287f4259363f/", "label": "Isolate host and submit reason", "button_text": "Open form" } ], "linked_cases": [], "opened_at": "2023-12-18T22:29:22Z", "resolved_at": null, "created_at": "2023-12-18T22:29:22Z", "updated_at": "2023-12-18T22:29:22Z", "records": [ { "id": 187, "results": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ] } ], "priority": "HIGH", "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ] } ``` ### Update ## Description Update a case. ## Request HTTP Method: **PUT** | Parameter | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | **Optional** The case name. | | team_id | **Optional** The ID of the team (or group) the case belongs to. | | description | **Optional** The case description. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | priority | **Optional** The case priority - critical, high, medium, low or info. | | status | **Optional** The case status - open or closed. | | sub_status_id | **Optional** The case sub-status ID. | | author_email | **Optional** The email of the user creating the cases. | | assignee_emails | **Optional** An array of user email addresses to assign to the case. Case will automatically be assigned to the user associated with the API token if none provided. | | add_assignee_emails | **Optional** An array of user email addresses to assign to the case. | | remove_assignee_emails | **Optional** An array of user email addresses to remove from the case. | | add_tag_names | **Optional** An array of tag names to add to the case. | | remove_tag_names | **Optional** An array of tag names to remove from the case. | | opened_at | **Optional** ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | **Optional** ISO 8601 Timestamp representing the date and time the case was resolved at. | | closure_conditions | **Optional** An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case.

**N.B.** The formula key should be passed as a raw formula wrapped in strings as opposed to a pill value. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated case name" }' ``` ## Response A successful request will return a JSON object describing the updated case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | sub_status | An object describing the case sub-status. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | activities | An array of team case actions taken within the case. | | activities_meta | Metadata defining pagination params required to fetch additional activities for the case. | | team | The team the case is within - ID & name. | | actions | An array of case actions for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case - ID & name. | | sla | An object describing the case SLA status. Times are in seconds. | | slas | An an array of SLAs for the case. Times are in seconds. | | fields | An array of field values for the case. | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case, grouped by record type. | | records_meta | Metadata defining pagination params required to fetch additional records for the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | | blocks | An array of block objects specifying the block title, slug, type, position, visibility, group, and element ids. | | tasks | An array of tasks associated with the case. | ### Sample response ```json { "case_id": 1, "name": "Case 1..25", "description": null, "status": "OPEN", "sub_status": { "id": 1, "name": "To do" }, "priority": "LOW", "url": "http:///team/276/cases/1", "metadata": { "foo": "bar" }, "author": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "opened_by": null, "resolved_by": null, "assignees": [ { "user_id": "176", "first_name": "Example", "last_name": "Person", "email": "person_10@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "178", "first_name": "Example", "last_name": "Person", "email": "person_12@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "180", "first_name": "Example", "last_name": "Person", "email": "person_14@example.com", "avatar_url": "", "is_service_account": false } ], "tags": [ { "id": 7, "name": "Tag 1" }, { "id": 8, "name": "Tag 2" }, { "id": 9, "name": "Tag 3" } ], "sla": { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, "slas": [ { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 100, "exceeded": true, "sla_type": "response" } ], "fields": [ { "id": 1, "value": "Windows 11", "case_input": { "id": 1, "key": "operating_system", "name": "Operating system", "validation_type": "none", "validation_options": {} } } ], "activities": [ { "id": 109, "activity_type": "CREATED", "value": "115", "user": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 111, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "170", "first_name": "Example", "last_name": "Person", "email": "person_4@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 113, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "172", "first_name": "Example", "last_name": "Person", "email": "person_6@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" } ], "team": { "id": 276, "name": "Test team 1" }, "linked_cases": [{ "case_id": 1, "name": "Case 1" }], "closure_conditions": [ { "formula": "=SIZE(team_case.assignees) > 2", "name": "Number of assignees" } ], "opened_at": "2024-03-25T15:40:39Z", "resolved_at": null, "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z", "records": [ { "record_type_id": 55, "record_type_name": "Record type 2", "record_type_record_results": [ { "id": 59, "results": [ { "id": 59110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 59109, "name": "Story name", "value": "Alert investigation" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 58, "results": [ { "id": 58110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 58109, "name": "Story name", "value": "Alert investigation #1" } ], "created_at": "2024-04-16T08:02:03Z" } ] }, { "record_type_id": 54, "record_type_name": "Record type 1", "record_type_record_results": [ { "id": 56, "results": [ { "id": 56108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 56107, "name": "Story name", "value": "Alert investigation #2" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 55, "results": [ { "id": 55108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 55107, "name": "Story name", "value": "Alert investigation #3" } ], "created_at": "2024-04-16T08:02:03Z" } ] } ], "actions": [ { "id": 7, "url": "http://example.com", "label": "Hello, world!", "action_type": "page" } ], "blocks": [ { "id": 1, "title": "Notes", "slug": "blk_notes", "block_type": "note", "position": 1, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 54, "id": 54 }, { "element_id": 674, "id": 674 }, { "element_id": 524, "id": 524 } ] }, { "id": 2, "title": "Additional notes", "slug": "blk_additional_notes", "block_type": "note", "position": 2, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 235, "id": 235 }, { "element_id": 342, "id": 342 }, { "element_id": 744, "id": 744 } ] } ], "tasks": [ { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123" }, { "id": "456" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Contact affected users", "completed": false, "assignees": [], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } ], "activities_meta": { "current_page": "https:///api/v2/cases/1/activities?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 }, "records_meta": { "current_page": "https:///api/v2/cases/1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a list of cases. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | team_id | **Optional** Retrieve cases for the specified team. | | filters | **Optional** Object specifying case filters (see the table below). | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 50. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | Supported parameters in `filters` | `filters` parameters | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | assigned_to_me | **Optional** A boolean (true or false). | | assignees | **Optional** An array of user IDs. | | assignee_emails | **Optional** An array of user email addresses. | | start_date | **Optional** A timestamp (ISO 8601 format). End date will default to today if not provided. | | end_date | **Optional** A timestamp (ISO 8601 format). | | search | **Optional** A string that searches against case name, description and ID. | | or_tags | **Optional** An array of tag names that are OR'd by. | | and_tags | **Optional** An array of tag names to AND'd by. | | tags | **Optional** An array of tag names (behaves the same as `and_tags`). | | records | **Optional** A string array of record result values. Cases containing a record matching any of the results provided will be returned. | | status | **Optional** `OPEN` or `CLOSED`. | | priority | **Optional** `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` or `INFO` | | metadata | **Optional** An object of metadata as key-value pairs | | author_emails | **Optional** An array of author emails. | ```bash curl -X GET \ https:///api/v1/cases \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the cases the requesting token has access to. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The case ID. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | team_case_actions | An array of team case actions taken within the case. | | team | The team the case is within - ID & name. | | team_case_buttons | An array of team case buttons for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case (IDs only). | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | ### Sample response ```json "cases": [ { "case_id": 42, "name": "Suspicious login detected", "description": "This is a high priority case created via the API", "status": "OPEN", "url": "https://tenant.tines.com/team/2/cases/42", "metadata": {}, "author": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "opened_by": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false }, "resolved_by": null, "assignees": [ { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "is_service_account": false } ], "tags": [ { "id":4, "name": "login" } ], "team_case_actions": [ { "id": 7508, "action": "CREATED", "value": "42", "user": {} } ], "team": { "id": 2, "name": "Team 1" }, "team_case_buttons": [ { "id": 8, "button_type": "webhook", "url": "http://tenant.tines.com/webhook/e840b4e8cf60437196d9a4bcb85d2de0/61441bc05fddfa4c09924b23fcf72b91", "label": "Isolate host" }, { "id": 9, "button_type": "page", "url": "https://tenant.tines.com/pages/55e94b9b4e26175051c0287f4259363f/", "label": "Isolate host and submit reason" } ], "linked_cases": [], "opened_at": "2023-12-18T22:29:22Z", "resolved_at":null, "created_at": "2023-12-18T22:29:22Z" , "updated_at": "2023-12-18T22:29:22Z", "records": [ { "id": 187, "results": [ { "id": 1871, "name": "Story name", "value": "Cases API" }, ] } ], "priority": "HIGH", "closure_conditions": [ { "name": "has at least 1 assignee", "formula": "=SIZE(team_case.assignees) > 0" } ] } ], "meta": { "current_page": "https:///api/v1/cases?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } ``` ### List ## Description Retrieve a list of cases. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | **Optional** Retrieve cases for the specified team. | | filters | **Optional** Object specifying case filters (see the table below). | | order | **Optional** `RECENTLY_EDITED`, `LEAST_RECENTLY_EDITED`, `PRIORITY_ASC`, `PRIORITY_DESC`, `OPENED_ASC`, `OPENED_DESC`, `CREATED_ASC` or `CREATED_DESC`. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 500. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | Supported parameters in `filters` | `filters` parameters | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Assignee filters** | | | assignees | **Optional** A single user ID, email address, the string `"unassigned"`, or an array of these values. Cases matching any of the specified assignees will be returned. Use `"unassigned"` to filter for cases with no assignees. | | and_assignees | **Optional** A single user ID or an array of user IDs. Cases must have all specified assignees (AND logic). | | exclude_assignees | **Optional** A single user ID or an array of user IDs to exclude. Cases with any of the specified assignees will be excluded. | | assigned_to_me | **Optional** A boolean (true or false). Filter cases assigned to the current user. | | assignee_emails | **Optional** A single email address or an array of user email addresses. **Deprecated**: Use `assignees` with email addresses instead. | | unassigned | **Optional** A boolean (true or false). **Deprecated**: Use `assignees: ["unassigned"]` instead. | | **Author filters** | | | authors | **Optional** A single author user ID, email address, the string `"tines"`, or an array of these values. Cases created by any of the specified authors will be returned. Use `"tines"` to filter for cases created via automation. | | exclude_authors | **Optional** A single author user ID or an array of author user IDs to exclude. Cases created by any of the specified authors will be excluded. | | author_emails | **Optional** A single email address or an array of author emails. **Deprecated**: Use `authors` with email addresses instead. | | **Tag filters** | | | tags | **Optional** A single tag name or an array of tag names (behaves the same as `and_tags`). Cases must have all specified tags. | | and_tags | **Optional** A single tag name or an array of tag names to AND'd by. Cases must have all specified tags. | | or_tags | **Optional** A single tag name or an array of tag names that are OR'd by. Cases matching any of the specified tags will be returned. | | exclude_tags | **Optional** A single tag name or an array of tag names to exclude by. Cases with any of the specified tags will be excluded. | | **Priority filters** | | | priority | **Optional** A single priority or an array of priorities. Valid values: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`. Cases matching any of the specified priorities will be returned. | | exclude_priorities | **Optional** A single priority or an array of priorities to exclude. Valid values: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`. | | **Status filters** | | | status | **Optional** `OPEN` or `CLOSED`. | | sub_status_names | **Optional** A single sub status name or an array of sub status names. Cases matching any of the specified sub statuses will be returned. | | exclude_sub_status_names | **Optional** A single sub status name or an array of sub status names to exclude. | | **Metadata filters** | | | metadata | **Optional** A single metadata object or an array of metadata objects. Each metadata object contains:
• `key`: The metadata key
• `value`: The metadata value. Uses AND logic (same as `and_metadata`). | | and_metadata | **Optional** A single metadata object or an array of metadata objects using AND logic. Each metadata object contains:
• `key`: The metadata key
• `value`: The metadata value. Cases must match all specified metadata entries. | | or_metadata | **Optional** A single metadata object or an array of metadata objects using OR logic. Each metadata object contains:
• `key`: The metadata key
• `value`: The metadata value. Cases matching any of the specified metadata entries will be returned. | | **Field filters** | | | fields | **Optional** A single field object or an array of field objects to filter by case input values. Each field object contains:
• `key`: The slug of the case input field (e.g., `<>` for a "Host name" field)
• `value`: The value to search for. Uses AND logic (same as `and_fields`). | | and_fields | **Optional** A single field object or an array of field objects to filter by case input values using AND logic. Each field object contains:
• `key`: The slug of the case input field
• `value`: The value to search for. Cases must match all specified fields. | | or_fields | **Optional** A single field object or an array of field objects to filter by case input values using OR logic. Each field object contains:
• `key`: The slug of the case input field
• `value`: The value to search for. Cases matching any of the specified fields will be returned. | | **Date filters** | | | start_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to start of day. Filters cases created on or after this date. | | end_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to end of day. Filters cases created before or on this date. | | relative_date | **Optional** A string specifying a relative date range. Valid values:
• `"today"` - Cases created today
• `"yesterday"` - Cases created yesterday
• `"X days"` or `"X day"` - Cases created in the last X days (e.g., `"7 days"`)
• `"X weeks"` or `"X week"` - Cases created in the last X weeks (e.g., `"2 weeks"`)
• `"X months"` or `"X month"` - Cases created in the last X months (e.g., `"1 month"`)
• `"X years"` or `"X year"` - Cases created in the last X years (e.g., `"1 year"`)
Filters cases by creation date. | | time_range | **Optional** A string specifying a time range filter in 24-hour format: `"HH:MM-HH:MM"` (e.g., `"09:00-17:00"`). If the start time is greater than the end time (e.g., `"22:00-06:00"`), it spans midnight. Filters cases by creation time within the specified range. | | resolved_at_start_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to start of day. Filters cases resolved on or after this date. | | resolved_at_end_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to end of day. Filters cases resolved before or on this date. | | resolved_at_relative_date | **Optional** A string specifying a relative date range for resolved date. Valid values:
• `"today"` - Cases resolved today
• `"yesterday"` - Cases resolved yesterday
• `"X days"` or `"X day"` - Cases resolved in the last X days (e.g., `"7 days"`)
• `"X weeks"` or `"X week"` - Cases resolved in the last X weeks
• `"X months"` or `"X month"` - Cases resolved in the last X months
• `"X years"` or `"X year"` - Cases resolved in the last X years | | updated_at_start_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to start of day. Filters cases updated on or after this date. | | updated_at_end_date | **Optional** A timestamp (ISO 8601 format). Date-only strings (YYYY-MM-DD) default to end of day. Filters cases updated before or on this date. | | updated_at_relative_date | **Optional** A string specifying a relative date range for updated date. Valid values:
• `"today"` - Cases updated today
• `"yesterday"` - Cases updated yesterday
• `"X days"` or `"X day"` - Cases updated in the last X days (e.g., `"7 days"`)
• `"X weeks"` or `"X week"` - Cases updated in the last X weeks
• `"X months"` or `"X month"` - Cases updated in the last X months
• `"X years"` or `"X year"` - Cases updated in the last X years | | **SLA filters** | | | sla_status | **Optional** A single SLA status or an array of SLA statuses. Valid values: `warning`, `exceeded`. Cases matching any of the specified SLA statuses will be returned (OR logic). | | and_sla_status | **Optional** A single SLA status or an array of SLA statuses. Valid values: `warning`, `exceeded`. Cases must match all specified SLA statuses (AND logic). | | exclude_sla_status | **Optional** A single SLA status or an array of SLA statuses to exclude. Valid values: `warning`, `exceeded`. Cases with any of the specified SLA statuses will be excluded. | | sla_type | **Optional** A single SLA type or an array of SLA types. Valid values: `resolution`, `response`. Cases matching any of the specified SLA types will be returned (OR logic). | | and_sla_type | **Optional** A single SLA type or an array of SLA types. Valid values: `resolution`, `response`. Cases must match all specified SLA types (AND logic). | | exclude_sla_type | **Optional** A single SLA type or an array of SLA types to exclude. Valid values: `resolution`, `response`. Cases with any of the specified SLA types will be excluded. | | sla | **Optional** A single SLA status or an array of SLA statuses. Valid values: `warning`, `exceeded`. Cases matching any of the specified SLA statuses will be returned (OR logic). **Deprecated**: Use `sla_status` instead. | | **Text search filters** | | | search | **Optional** A string that searches against case name, description and ID. | | name | **Optional** A string that searches against case name. | | comment | **Optional** A string that searches against case comments. | | note | **Optional** A string that searches against case notes. | | **Other filters** | | | case_ids | **Optional** A single case ID or an array of case IDs. | | child_team_ids | **Optional** A single child team ID or an array of child team IDs. Filter cases belonging to the specified teams. | | records | **Optional** A single record result value or an array of record result values (strings). Cases containing a record matching any of the results provided will be returned. Note: Large text record fields are not queryable in this instance. | | subscribed | **Optional** A boolean (true or false). Filter cases the current user is subscribed to. | | my_open_tasks | **Optional** A boolean (true or false). Filter cases that have open tasks assigned to the current user. | ```bash curl -X GET \ https:///api/v2/cases \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Example request with search filters Sample request params: ```json { "team_id": "1", "filters": { "search": "Sample search string", "status": "OPEN", "priority": ["HIGH", "CRITICAL"], "fields": [ { "key": "company", "value": "Tines" } ] }, "order": "OPENED_DESC", "per_page": "10" } ``` Example request: ```bash curl -v \ -X GET \ --location \ "https:///api/v2/cases/?order=OPENED_DESC&per_page=10&team_id=1" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ --data '{ "filters": { "status": "OPEN", "priority": ["HIGH", "CRITICAL"], "fields": [ { "key": "version", "value": "2.0" } ] } }' ``` ## Response A successful request will return a JSON object containing the cases the requesting token has access to. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | sub_status | An object describing the case sub-status. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | fields | An array of field values for the case. | | activities | An array of team case actions taken within the case. | | activities_meta | Metadata defining pagination params required to fetch additional activities for the case. | | team | The team the case is within - ID & name. | | actions | An array of case actions for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case - ID & name. | | sla | An object describing the case SLA status. Times are in seconds. | | slas | An array of SLAs for the case. Times are in seconds. | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case, grouped by record type. Each record result includes the field id, name, and value. | | records_meta | Metadata defining pagination params required to fetch additional records for the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | | blocks | An array of block objects specifying the block title, slug, type, position, visibility, group, and element ids. | | tasks | An array of tasks associated with the case. | ### Sample response ```json { "cases": [ { "case_id": 1, "name": "Case 1..25", "description": null, "status": "OPEN", "sub_status": { "id": 1, "name": "To do" }, "priority": "LOW", "url": "http:///team/276/cases/1", "metadata": { "foo": "bar" }, "author": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "opened_by": null, "resolved_by": null, "assignees": [ { "user_id": "176", "first_name": "Example", "last_name": "Person", "email": "person_10@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "178", "first_name": "Example", "last_name": "Person", "email": "person_12@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "180", "first_name": "Example", "last_name": "Person", "email": "person_14@example.com", "avatar_url": "", "is_service_account": false } ], "tags": [ { "id": 7, "name": "Tag 1" }, { "id": 8, "name": "Tag 2" }, { "id": 9, "name": "Tag 3" } ], "sla": { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, "slas": [ { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 100, "exceeded": true, "sla_type": "response" } ], "activities": [ { "id": 109, "activity_type": "CREATED", "value": "115", "user": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 111, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "170", "first_name": "Example", "last_name": "Person", "email": "person_4@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 113, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "172", "first_name": "Example", "last_name": "Person", "email": "person_6@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" } ], "team": { "id": 276, "name": "Test team 1" }, "linked_cases": [{ "case_id": 1, "name": "Case 1" }], "closure_conditions": [ { "formula": "=SIZE(team_case.assignees) > 2", "name": "Number of assignees" } ], "opened_at": "2024-03-25T15:40:39Z", "resolved_at": null, "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z", "records": [ { "record_type_id": 55, "record_type_name": "Record type 2", "record_type_record_results": [ { "id": 59, "results": [ { "id": 59110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 59109, "name": "Story name", "value": "Alert investigation" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 58, "results": [ { "id": 58110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 58109, "name": "Story name", "value": "Alert investigation #1" } ], "created_at": "2024-04-16T08:02:03Z" } ] }, { "record_type_id": 54, "record_type_name": "Record type 1", "record_type_record_results": [ { "id": 56, "results": [ { "id": 56108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 56107, "name": "Story name", "value": "Alert investigation #2" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 55, "results": [ { "id": 55108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 55107, "name": "Story name", "value": "Alert investigation #3" } ], "created_at": "2024-04-16T08:02:03Z" } ] } ], "actions": [ { "id": 7, "url": "http://example.com", "label": "Hello, world!", "action_type": "page" } ], "fields": [ { "id": 1, "value": "Tines", "case_input": { "id": 1, "key": "company", "name": "Company", "validation_type": "none", "validation_options": {} } } ], "blocks": [ { "id": 1, "title": "Notes", "slug": "blk_notes", "block_type": "note", "position": 1, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 54, "id": 54 }, { "element_id": 674, "id": 674 }, { "element_id": 524, "id": 524 } ] }, { "id": 2, "title": "Additional notes", "slug": "blk_additional_notes", "block_type": "note", "position": 2, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 235, "id": 235 }, { "element_id": 342, "id": 342 }, { "element_id": 744, "id": 744 } ] } ], "tasks": [ { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123" }, { "id": "456" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Contact affected users", "completed": false, "assignees": [], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } ], "activities_meta": { "current_page": "https:///api/v2/cases/1/activities?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 }, "records_meta": { "current_page": "https:///api/v2/cases/1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 4 } } ], "meta": { "current_page": "https:///api/v2/cases?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Delete a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer ' ``` ## Response A successful request will return an empty response with a `204` status code. ### Delete ## Description Delete a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer ' ``` ## Response A successful request will return an empty response with a `204` status code. ### Append ## Description Append to the case description. ## Request HTTP Method: **POST** | Parameter | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | description | The additional case description content. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/description \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"description": "...This is additional content to append to the existing description"}' ``` ## Response A successful request will return a JSON object describing the updated case. ### Field description | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | name | The case name. | | description | The case description. | | status | The case status - open or closed. | | sub_status | An object describing the case sub-status. | | url | The case URL. | | metadata | Case related metadata represented as key-value pairs. | | author | An object describing the case author. | | opened_by | An object describing the user who opened the case. | | resolved_by | An object describing the user who resolved the case. | | assignees | An array of users assigned to the case. | | tags | An array of tags associated with the case. | | activities | An array of team case actions taken within the case. | | activities_meta | Metadata defining pagination params required to fetch additional activities for the case. | | team | The team the case is within - ID & name. | | actions | An array of case actions for downstream actions associated with the case. | | linked_cases | An array of cases linked to this case - ID & name. | | sla | An object describing the case SLA status. Times are in seconds. | | slas | An array of SLAs for the case. Times are in seconds. | | fields | An array of field values for the case. | | opened_at | ISO 8601 Timestamp representing the date and time the case was opened at. | | resolved_at | ISO 8601 Timestamp representing the date and time the case was resolved at. | | created_at | ISO 8601 Timestamp representing the date and time the case was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the case was updated at. | | records | An array of records associated with the case, grouped by record type. | | records_meta | Metadata defining pagination params required to fetch additional records for the case. | | priority | The case priority - critical, high, medium, low or info. | | closure_conditions | An array of closure requirements in the form of a set of formula rules that need to evaluate to true to enable the closing of a case. | | blocks | An array of block objects specifying the block type and block element ids. | | tasks | An array of tasks associated with the case. | ### Sample response ```json { "case_id": 1, "name": "Case 1..25", "description": "This is a high priority case created via the API...This is additional content to append to the description", "status": "OPEN", "sub_status": { "id": 1, "name": "To do" }, "priority": "LOW", "url": "http:///team/276/cases/1", "metadata": { "foo": "bar" }, "author": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "opened_by": null, "resolved_by": null, "assignees": [ { "user_id": "176", "first_name": "Example", "last_name": "Person", "email": "person_10@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "178", "first_name": "Example", "last_name": "Person", "email": "person_12@example.com", "avatar_url": "", "is_service_account": false }, { "user_id": "180", "first_name": "Example", "last_name": "Person", "email": "person_14@example.com", "avatar_url": "", "is_service_account": false } ], "tags": [ { "id": 7, "name": "Tag 1" }, { "id": 8, "name": "Tag 2" }, { "id": 9, "name": "Tag 3" } ], "sla": { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, "slas": [ { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 0, "exceeded": false, "sla_type": "completion" }, { "remaining_time_seconds": 0, "current_time_seconds": 0, "percent_elapsed": 100, "exceeded": true, "sla_type": "response" } ], "fields": [ { "id": 1, "value": "Windows 11", "case_input": { "id": 1, "name": "Operating system" } } ], "activities": [ { "id": 109, "activity_type": "CREATED", "value": "115", "user": { "user_id": "168", "first_name": "Example", "last_name": "Person", "email": "person_2@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 111, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "170", "first_name": "Example", "last_name": "Person", "email": "person_4@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" }, { "id": 113, "activity_type": "COMMENTED", "value": "I'm a comment", "user": { "user_id": "172", "first_name": "Example", "last_name": "Person", "email": "person_6@example.com", "avatar_url": "", "is_service_account": false }, "created_at": "2024-03-25T15:40:39Z" } ], "team": { "id": 276, "name": "Test team 1" }, "linked_cases": [{ "case_id": 1, "name": "Case 1" }], "closure_conditions": [ { "formula": "=SIZE(team_case.assignees) > 2", "name": "Number of assignees" } ], "opened_at": "2024-03-25T15:40:39Z", "resolved_at": null, "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z", "records": [ { "record_type_id": 55, "record_type_name": "Record type 2", "record_type_record_results": [ { "id": 59, "results": [ { "id": 59110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 59109, "name": "Story name", "value": "Alert investigation" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 58, "results": [ { "id": 58110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 58109, "name": "Story name", "value": "Alert investigation #1" } ], "created_at": "2024-04-16T08:02:03Z" } ] }, { "record_type_id": 54, "record_type_name": "Record type 1", "record_type_record_results": [ { "id": 56, "results": [ { "id": 56108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 56107, "name": "Story name", "value": "Alert investigation #2" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 55, "results": [ { "id": 55108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 55107, "name": "Story name", "value": "Alert investigation #3" } ], "created_at": "2024-04-16T08:02:03Z" } ] } ], "actions": [ { "id": 7, "url": "http://example.com", "label": "Hello, world!", "action_type": "page" } ], "blocks": [ { "id": 1, "block_type": "note", "elements": [ { "element_id": 54, "id": 54 }, { "element_id": 674, "id": 674 }, { "element_id": 524, "id": 524 } ] }, { "id": 2, "block_type": "note", "elements": [ { "element_id": 235, "id": 235 }, { "element_id": 342, "id": 342 }, { "element_id": 744, "id": 744 } ] } ], "tasks": [ { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123" }, { "id": "456" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Contact affected users", "completed": false, "assignees": [], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } ], "activities_meta": { "current_page": "https:///api/v2/cases/1/activities?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 }, "records_meta": { "current_page": "https:///api/v2/cases/1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Actions #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Create a new case button on a specified case. This does not overwrite other buttons that may exist on the case. ## Request HTTP Method: **POST** | Parameter | Description | | ----------- | ----------------------------------------------------------- | | url | The URL of the case button (webhook or page URL). | | label | User specified field to identify the case button. | | button_type | The case button type (`webhook` or `page`). | | button_text | **Optional** The text for the button to execute the action. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/buttons \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "url": "https://example.tines.com", "label": "label", "button_type": "webhook", "button_text": "Open form" }' ``` ## Response A successful request will return a JSON object describing the newly created case button. ### Field description | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------ | | case_id | The case ID. | | id | The case button ID. | | url | The URL of the case button. | | label | The label of the case button. | | button_type | The case button type (`webhook` or `page`). | | button_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | created_at | ISO 8601 Timestamp representing creation date and time of the case button. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case button. | ### Sample response ```json { "case_id": 42, "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "button_type": "webhook", "button_text": "Claim", "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ``` #### Create ## Description Create a new case action on a specified case. This does not overwrite other actions that may exist on the case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------------ | | url | The URL of the case action (webhook or page URL). | | label | User specified field to identify the case action. | | action_type | The case action type (`webhook` or `page`). | | action_text | **Optional** The text for the button to execute the action. | | query_params | **Optional** An object of key-value pairs to append as query parameters to the action URL. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/actions \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "url": "https://example.tines.com", "label": "label", "action_type": "webhook", "action_text": "Open form", "query_params": { "status": "open", "priority": "high" } }' ``` ## Response A successful request will return a JSON object describing the newly created case action. ### Field description | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------ | | case_id | The ID of the case. | | id | The case action ID. | | url | The URL of the case action. | | label | The label of the case action. | | action_type | The case action type (`webhook` or `page`). | | action_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | query_params | An object of key-value pairs to append as query parameters to the action URL. | | created_at | ISO 8601 Timestamp representing creation date and time of the case action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case action. | ### Sample response ```json { "case_id": 42, "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "action_type": "webhook", "action_text": "Open form", "query_params": { "priority": "high" }, "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ``` #### Get | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a specific case button. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ---------------------- | | case_id | ID of the case. | | id | ID of the case button. | ```bash curl -X GET \ https:///api/v1/cases/<>/buttons/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a case button. ### Field description | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------ | | case_id | The case ID. | | id | The case button ID. | | url | The URL of the case button. | | label | The label of the case button. | | button_type | The case button type (`webhook` or `page`). | | button_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | created_at | ISO 8601 Timestamp representing creation date and time of the case button. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case button. | ### Sample response ```json { "case_id": 42, "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "button_type": "webhook", "button_text": "Claim", "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ``` #### Get ## Description Retrieve a specific case action. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------------- | | case_id | The ID of the case. | | id | The ID of the case action. | ```bash curl -X GET \ https:///api/v2/cases/<>/actions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a case button. ### Field description | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------ | | case_id | The ID of the case. | | id | The case button ID. | | url | The URL of the case button. | | label | The label of the case button. | | action_type | The case action type (`webhook` or `page`). | | action_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | query_params | An object of key-value pairs to append as query parameters to the action URL. | | created_at | ISO 8601 Timestamp representing creation date and time of the case button. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case button. | ### Sample response ```json { "case_id": 42, "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "action_type": "webhook", "action_text": "Open form", "query_params": { "priority": "high" }, "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ``` #### Update | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Use a HTTP PUT request to update an existing case button. ## Request HTTP Method: **PUT** | Parameter | Description | | ----------- | -------------------------------------------------------------- | | url | **Optional** The URL of the case button (webhook or page URL). | | label | **Optional** User specified field to identify the case button. | | button_type | **Optional** The case button type (`webhook` or `page`). | | button_text | **Optional** The text for the button to execute the action. | | Path Parameter | Description | | -------------- | ----------------- | | case_id | ID of the case. | | id | ID of the button. | ### Sample request ```bash curl -X PUT \ https:///api/v1/cases/<>/buttons/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "url": "https://example.com" }' ``` ## Response A successful request will return a JSON object describing the updated case button. ### Field description | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------ | | case_id | The case ID. | | id | The case button ID. | | url | The URL of the case button. | | label | The label of the case button. | | button_type | The case button type (`webhook` or `page`). | | button_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | created_at | ISO 8601 Timestamp representing creation date and time of the case button. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case button. | ### Sample response ```json { "case_id": 42, "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "button_type": "webhook", "button_text": "Claim", "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ``` #### Update ## Description Use a HTTP PUT request to update an existing case action. ## Request HTTP Method: **PUT** | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------------ | | url | **Optional** The URL of the case action (webhook or page URL). | | label | **Optional** User specified field to identify the case action. | | action_type | **Optional** The case action type (`webhook` or `page`). | | action_text | **Optional** The text for the button to execute the action. | | query_params | **Optional** An object of key-value pairs to append as query parameters to the action URL. | | Path Parameter | Description | | -------------- | --------------------- | | case_id | The ID of the case. | | id | The ID of the action. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/actions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "url": "https://example.com" }' ``` ## Response A successful request will return a JSON object describing the updated case action. ### Field description | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------ | | case_id | The ID of the case. | | id | The case action ID. | | url | The URL of the case action. | | label | The label of the case action. | | action_type | The case action type (`webhook` or `page`). | | action_text | The text for the button to execute the action. | | query_params | An object of key-value pairs to append as query parameters to the action URL. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | created_at | ISO 8601 Timestamp representing creation date and time of the case action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case action. | ### Sample response ```json { "case_id": 42, "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "action_type": "webhook", "action_text": "Open form", "query_params": { "priority": "high" }, "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ``` #### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a list of case buttons for a specific case. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X GET \ https:///api/v1/cases/<>/buttons \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array containing the case buttons on the specified case provided the requesting token has access to it. ### Field description | Parameter | Description | | ----------- | ------------------------------------------------------------------------------------ | | case_id | The case ID. | | id | The case button ID. | | url | The URL of the case button. | | label | The label of the case button. | | button_type | The case button type (`webhook` or `page`). | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | created_at | ISO 8601 Timestamp representing creation date and time of the case button. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case button. | ### Sample response ```json "case_id": 1, "team_case_buttons": [ { "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "button_type": "webhook", "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" }, { "id": 2, "url": "https://tenant.tines.com/webhook/abc/", "label": "Escalate", "story_name": "Case Management", "story_emoji": ":rocket:", "page_emoji": null, "button_type": "webhook", "created_at": "2023-10-31T17:42:00Z", "updated_at": "2023-10-31T18:42:00Z" } ] ``` #### List ## Description Retrieve a list of case actions for a specific case. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ### Sample request ```bash curl -X GET \ https:///api/v2/cases/<>/actions \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array containing the case actions on the specified case provided the requesting token has access to it. ### Field description | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------ | | case_id | The ID of the case. | | id | The case action ID. | | url | The URL of the case action. | | label | The label of the case action. | | action_type | The case action type (`webhook` or `page`). | | action_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | query_params | An object of key-value pairs to append as query parameters to the action URL. | | created_at | ISO 8601 Timestamp representing creation date and time of the case action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case action. | ### Sample response ```json { "case_id": 1, "actions": [ { "id": 1, "url": "https://tenant.tines.com/webhook/abc/", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "action_type": "webhook", "action_text": "Open form", "query_params": { "assignee": "john@doe.com" }, "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" }, { "id": 2, "url": "https://tenant.tines.com/webhook/abc/", "label": "Escalate", "story_name": "Case Management", "story_emoji": ":rocket:", "page_emoji": null, "action_type": "webhook", "action_text": "Open page", "query_params": { "status": "open", "priority": "high" }, "created_at": "2023-10-31T17:42:00Z", "updated_at": "2023-10-31T18:42:00Z" } ], "meta": { "count": 2, "current_page": "https:///api/v2/cases/1/actions?per_page=20&page=1", "next_page": null, "next_page_number": null, "pages": 1, "per_page": 20, "previous_page": null } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Delete an existing case button. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | -------------------------------- | | case_id | ID of the case. | | id | ID of the case button to delete. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/buttons/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Delete an existing case action. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | -------------------------------- | | case_id | The ID of the case. | | id | ID of the case action to delete. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/actions/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Batch update ## Description Update the actions on a case. This request will replace any existing actions on the case. ## Request HTTP Method: **PUT** | Actions Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------ | | url | The URL of the case action (webhook or page URL). | | label | User specified field to identify the case action. | | action_type | The case action type (`webhook` or `page`). | | action_text | **Optional** The text for the button to execute the action. | | query_params | **Optional** An object of key-value pairs to append as query parameters to the action URL. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/actions/batch \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "actions": [ { "url": "https://tenant.tines.com/pages/123", "label": "Complete request", "action_type": "page", "action_text": "Open", "query_params": { "status": "done" } }, { "url": "https://tenant.tines.com/webhook/abc", "label": "Claim case", "action_type": "webhook", "action_text": "Run", "query_params": { "status": "open" } } ] }' ``` ## Response A successful request will return a JSON object describing the updated case action. ### Field description | Parameter | Description | | --------- | ---------------------------------- | | case_id | The ID of the case. | | actions | An array of the actions on a case. | | Action object | Description | | ------------- | ------------------------------------------------------------------------------------ | | id | The case action ID. | | url | The URL of the case action. | | label | The label of the case action. | | action_type | The case action type (`webhook` or `page`). | | action_text | The text for the button to execute the action. | | story_name | Will be populated if the URL matches that of a page or webhook in an existing story. | | story_emoji | The associated story's emoji icon. | | page_emoji | The associated page's emoji icon. | | created_at | ISO 8601 Timestamp representing creation date and time of the case action. | | updated_at | ISO 8601 Timestamp representing last updated date and time of case action. | ### Sample response ```json { "case_id": 42, "actions": [ { "id": 1, "url": "https://tenant.tines.com/webhook/abc", "label": "Claim case", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": null, "action_type": "webhook", "action_text": "Run", "query_params": { "assignee": "john@doe.com" }, "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" }, { "id": 1, "url": "https://tenant.tines.com/pages/123", "label": "Complete request", "story_name": "Case Management", "story_emoji": ":fire:", "page_emoji": ":fire:", "action_type": "page", "action_text": "Open page", "query_params": { "status": "open", "priority": "high" }, "created_at": "2023-10-31T15:42:00Z", "updated_at": "2023-10-31T16:42:00Z" } ] } ``` ### Activities #### Get ## Description Retrieve a single case activity. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ---------------------------- | | case_id | The ID of the case. | | activity_id | The ID of the case activity. | ```bash curl -X GET \ https:///api/v2/cases/<>/activities/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the case activity. ### Field description | Parameter | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The activity ID. | | activity_type | The type of activity. | | value | The value of the activity. | | file | An object describing the file attached to the activity. Available only for `FILE_ATTACHED` or `FILE_ATTACHED_AND_COMMENTED` type activities. | | user | An object describing the user who performed the activity. | | created_at | The timestamp of the activity. | ### Sample response ```json { "case_id": 10, "id": 10, "activity_type": "FILE_ATTACHED_AND_COMMENTED", "value": "This is a case comment", "file": { "filename": "foo", "url": "http:///api/v2/cases/10/files/10/download" }, "user": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2023-07-18T10:27:18Z" } ``` #### List ## Description Retrieve a list of case activities for a case. These activities are logged on the case timeline and can be filtered by type. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | case_id | Retrieve activities for the specified case. | | activity_type | **Optional** An array of types of activities requested. See the list below for supported types. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 50. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | Supported activity types - `CREATED` - `ASSIGNED` - `UNASSIGNED` - `STATUS_UPDATED` - `SUB_STATUS_UPDATED` - `SEVERITY_UPDATED` - `COMMENTED` - `DELETED_COMMENT` - `DESCRIPTION_UPDATED` - `FIELD_UPDATED` - `FILE_ATTACHED` - `FILE_ATTACHED_AND_COMMENTED` - `FILE_DELETED` - `TAGS_ADDED` - `TAGS_REMOVED` - `RECORD_RESULT_SET_ADDED` - `RECORD_RESULT_SET_REMOVED` - `CHECKLIST_ITEM_COMPLETED` - `CHECKLIST_ITEM_INCOMPLETE` - `LINKED_CASE_ADDED` - `LINKED_CASE_REMOVED` - `METADATA_UPDATED` - `NOTE_ADDED` - `NOTE_DELETED` - `NOTE_UPDATED` - `SLA_WARNING` - `SLA_EXCEEDED` - `TASK_CREATED` - `TASK_DELETED` - `TASK_COMPLETED` - `TASK_INCOMPLETE` - `TASK_UPDATED` - `TASK_ASSIGNED` - `TASK_UNASSIGNED` - `TEAM_UPDATED` - `TITLE_UPDATED` ```bash curl -X GET \ https:///api/v2/cases/<>/activities?activity_type=%5B%5D=<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the cases the requesting token has access to. ### Field description | Parameter | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | id | The activity ID. | | activity_type | The type of activity. | | value | The value of the activity. | | file | An object describing the file attached to the activity. Available only for `FILE_ATTACHED` or `FILE_ATTACHED_AND_COMMENTED` type activities. | | user | An object describing the user who performed the activity. | | created_at | The timestamp of the activity. | ### Sample response ```json { "case_id": 10, "activities": [ { "id": 10, "activity_type": "FILE_ATTACHED_AND_COMMENTED", "value": "This is a case comment", "file": { "filename": "foo", "url": "http:///api/v2/cases/10/files/10/download" }, "user": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2023-07-18T10:27:18Z" } ], "meta": { "current_page": "https:///api/v2/cases/<>/activities?activity_type=%5B%5D=<>?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Assignees #### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a list of assignees of a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/cases/<>/assignees \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the assignees. ### Field description | Parameter | Description | | --------- | --------------------------------------- | | case_id | The case ID. | | assignees | An array of users assigned to the case. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "assignees": [ { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } ], "meta": { "current_page": "https:///api/v1/cases/42/assignees?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### List ## Description Retrieve a list of assignees of a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/assignees \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the assignees. ### Field description | Parameter | Description | | --------- | --------------------------------------- | | case_id | The case ID. | | assignees | An array of users assigned to the case. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "assignees": [ { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } ], "meta": { "current_page": "https:///api/v2/cases/42/assignees?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` ### Blocks #### Create ## Description Add a block to a case. ## Request HTTP Method: **POST** | Parameter | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | title | The title of the block. | | block_type | The type of block to create - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | elements | **Optional** An array of elements to add to the block. | | position | **Optional** The zero-indexed position of the block in the case. | | hidden | **Optional** A boolean (true or false). | | block_group_id | **Optional** The ID or slug of a group block to nest this block within. Slugs are prefixed with `blk_` (e.g. `blk_my_group`). | | author_email | **Optional** The email address of the author of the block. | ### Element Parameters #### Note Element Parameters | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | **Optional** The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | ------------- | ---------------------------------------------- | | filename | The name of the file. | | file_contents | The base64-encoded contents of the file. | | annotation | **Optional** The annotation text for the file. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request for a note block ```bash curl -X POST \ https:///api/v2/cases/<>/blocks \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "title": "My Note Block", "block_type": "note", "author_email": "jane@tines.io", "elements": [ { "content": "This is a note element", "note_type": "text", "color": "white" } ], "position": 0 }' ``` ### Sample request for a file block ```bash curl -X POST \ https:///api/v2/cases/<>/blocks \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "title": "My File Block", "block_type": "file", "elements": [ { "filename": "example.txt", "file_contents": "SGVsbG8gV29ybGQ=" } ], "position": 1 }' ``` ## Response A successful request will return a JSON object describing the created block. ### Field description | Parameter | Description | | --------- | ----------------- | | block | The block object. | | Block Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | id | The ID of the block record attached to the case. | | slug | A human-readable identifier for the block, prefixed with `blk_`. Auto-generated from the block title. | | title | The title of the block. | | block_type | The type of the block - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | position | The position of the block in the case. | | hidden | Boolean indicating whether the block is hidden. | | block_group_id | The ID of the block group this block is nested in. | | elements | An array of elements contained within the block. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - options: note, file. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | -------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | --------- | ------------------------------------------------------ | | file | Object containing file information (filename and url). | ### Sample response for a note block ```json { "block": { "id": 123, "slug": "blk_my_note_block", "title": "My Note Block", "block_type": "note", "position": 0, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 456, "id": 123, "element_type": "note", "content": "This is a note element", "note_type": "text", "color": "white", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } ], "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } } ``` #### Get ## Description Retrieve a single block for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | block_id | The ID or slug of the block. Slugs are prefixed with `blk_` (e.g. `blk_my_note_block`). | ```bash curl -X GET \ https:///api/v2/cases/<>/blocks/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` > You can use a block's slug in place of a numeric ID in this endpoint. For example, `/api/v2/cases/1/blocks/blk_note_block`. ## Response A successful request will return a JSON object of the block. ### Field description | Parameter | Description | | --------- | ----------------- | | block | The block object. | | Block Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | id | The ID of the block record attached to the case. | | slug | A human-readable identifier for the block, prefixed with `blk_`. Auto-generated from the block title. | | title | The title of the block. | | block_type | The type of the block - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | position | The position of the block in the case. | | hidden | Boolean indicating whether the block is hidden. | | block_group_id | The ID of the block group this block is nested in. | | elements | An array of elements contained within the block. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - matches the block_type. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | --------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | --------- | ------------------------------------------------------ | | file | Object containing file information (filename and url). | ### Sample response ```json { "block": { "id": 123, "slug": "blk_note_block", "title": "Note Block", "block_type": "note", "position": 1, "hidden": false, "block_group_id": 456, "elements": [ { "element_id": 456, "id": 123, "element_type": "note", "content": "This is a note element", "note_type": "text", "color": "white", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } ], "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } } ``` #### Update ## Description Update an existing block. ## Request HTTP Method: **PUT** | Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | title | **Optional** The title of the block. | | position | **Optional** The zero-indexed position of the block in the case. | | hidden | **Optional** A boolean (true or false). | | block_group_id | **Optional** The ID or slug of a block group to nest this block within, or `null` to remove it from a block group. Slugs are prefixed with `blk_` (e.g. `blk_my_group`). | | Path Parameter | Description | | -------------- | --------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | block_id | The ID or slug of the block. Slugs are prefixed with `blk_` (e.g. `blk_my_note_block`). | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/blocks/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "title": "Updated Block Title", "position": 2 }' ``` ## Response A successful request will return a JSON object describing the updated block. ### Field description | Parameter | Description | | --------- | ----------------- | | block | The block object. | | Block Parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The ID of the block record attached to the case. | | slug | A human-readable identifier for the block, prefixed with `blk_`. Auto-generated from the block title. Updating the title will regenerate the slug. | | title | The title of the block. | | block_type | The type of the block - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | position | The position of the block in the case. | | hidden | Boolean indicating whether the block is hidden. | | block_group_id | The ID of the block group this block is nested in. | | elements | An array of elements contained within the block. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - options: note, file. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | -------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | --------- | ------------------------------------------------------ | | file | Object containing file information (filename and url). | ### Sample response ```json { "block": { "id": 123, "slug": "blk_updated_block_title", "title": "Updated Block Title", "block_type": "note", "position": 2, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 456, "id": 123, "element_type": "note", "content": "This is a note element", "note_type": "text", "color": "white", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } ], "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-08T10:15:30Z" } } ``` #### List ## Description Retrieve a list of blocks for a case. ## Request HTTP Method: **GET** | Parameter | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | block_type | **Optional** Filter blocks by type - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/blocks \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the blocks. ### Field description | Parameter | Description | | --------- | --------------------------------------------- | | blocks | An array of block objects attached to a case. | | Block Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | id | The ID of the block record attached to the case. | | slug | A human-readable identifier for the block, prefixed with `blk_`. Auto-generated from the block title. | | title | The title of the block. | | block_type | The type of the block - options: note, file, linked_cases, metadata, closure_conditions, case_action, block_group and html. | | position | The position of the block in the case. | | hidden | Boolean indicating whether the block is hidden. | | block_group_id | The ID of the block group this block is nested in. | | elements | An array of elements contained within the block. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - options: note, file. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | -------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | --------- | ------------------------------------------------------ | | file | Object containing file information (filename and url). | ### Sample response ```json { "blocks": [ { "id": 123, "slug": "blk_note_block", "title": "Note Block", "block_type": "note", "position": 0, "hidden": false, "block_group_id": null, "elements": [ { "element_id": 456, "id": 123, "element_type": "note", "content": "This is a note element", "note_type": "text", "color": "white", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } ], "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" }, { "id": 124, "slug": "blk_file_block", "title": "File Block", "block_type": "file", "position": 1, "hidden": false, "elements": [ { "id": 457, "element_type": "file", "file": { "filename": "example.txt", "url": "https://example.com/files/example.txt" }, "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:43:58Z", "updated_at": "2025-01-07T11:43:58Z" } ], "created_at": "2025-01-07T11:43:58Z", "updated_at": "2025-01-07T11:43:58Z" } ] } ``` #### Delete ## Description Delete a block from a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | ---------------- | -------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | block_id | The ID or slug of the block. Slugs are prefixed with `blk_` (e.g. `blk_my_note_block`). | | include_children | (For group blocks only) Boolean flag indicating whether the block's child blocks should be deleted | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/blocks/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Elements ##### Get ## Description Retrieve a single element from a block. ## Request HTTP Method: **GET** | Parameter | Description | | ---------- | ---------------------- | | case_id | The ID of the case. | | block_id | The ID of the block. | | element_id | The ID of the element. | ```bash curl -X GET \ https:///api/v2/cases/<>/blocks/<>/elements/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object of the element. ### Field description #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - options: note, file. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | -------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | --------- | ------------------------------------------------------ | | file | Object containing file information (filename and url). | ### Sample response for a note element ```json { "element_id": 456, "id": 123, "element_type": "note", "content": "This is a note element", "note_type": "text", "color": "white", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z" } ``` ### Sample response for a file element ```json { "id": 457, "element_type": "file", "file": { "filename": "example.txt", "url": "https://example.com/files/example.txt" }, "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:43:58Z", "updated_at": "2025-01-07T11:43:58Z" } ``` ##### Update ## Description Update an existing element in a block. Currently, note elements and file elements can be updated. ## Request HTTP Method: **PUT** ### Note Element Parameters | Parameter | Description | | ------------ | --------------------------------------------------------------------------------------------------- | | content | **Optional** The content of the note. | | color | **Optional** The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | author_email | **Optional** The email address of the author of the note. | ### File Element Parameters | Parameter | Description | | ---------- | ---------------------------------------------- | | annotation | **Optional** The annotation text for the file. | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | The ID of the case. | | block_id | The ID of the block. | | element_id | The ID of the element. | ### Sample request for updating a note element ```bash curl -X PUT \ https:///api/v2/cases/<>/blocks/<>/elements/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "content": "This is an updated note element", "color": "blue", "author_email": "jane@tines.io" }' ``` ### Sample request for updating a file annotation ```bash curl -X PUT \ https:///api/v2/cases/<>/blocks/<>/elements/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "annotation": "This is an annotation for the attached file" }' ``` ## Response A successful request will return a JSON object describing the updated element. ### Field description #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - options: note, file. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | -------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | #### File Element Parameters | Parameter | Description | | ---------- | ---------------------------------------------------------------- | | file | Object containing file information. | | annotation | The annotation text associated with the file, if one is present. | | File parameter | Description | | -------------- | ----------------------------- | | filename | The name of the file. | | url | The URL to download the file. | ### Sample response for a note element ```json { "element_id": 456, "id": 123, "element_type": "note", "content": "This is an updated note element", "note_type": "text", "color": "blue", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-08T10:15:30Z" } ``` ### Sample response for a file element with annotation ```json { "element_id": 789, "id": 456, "element_type": "file", "file": { "filename": "report.pdf", "url": "https://example.com/api/v2/cases/123/files/456/download" }, "annotation": "This is an annotation for the attached file", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-08T10:15:30Z" } ``` ##### Append ## Description Append to the element content. Only note elements can be appended to. ## Request HTTP Method: **POST** ### Note Element Parameters | Parameter | Description | | ------------ | --------------------------------------------------------- | | content | The additional content of the element. | | author_email | **Optional** The email address of the author of the note. | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | The ID of the case. | | block_id | The ID of the block. | | element_id | The ID of the element. | ### Sample request for appending to a note element ```bash curl -X POST \ https:///api/v2/cases/<>/blocks/<>/elements/<>/content \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"content": "...This is additional content to append to the existing content."}' ``` ## Response A successful request will return a JSON object describing the updated element. ### Field description #### Common Element Parameters | Parameter | Description | | ------------ | ----------------------------------------------------------- | | element_id | The unique ID of this element within the current block. | | id | The original/source ID of the element. | | element_type | The type of the element - options: note, file. | | author | Details of the author of the element. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | #### Note Element Parameters | Parameter | Description | | --------- | -------------------------------------------------------------------------------------- | | content | The content of the note. | | note_type | The type of note - "html" for html blocks and "text" for any others. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | ### Sample response for a note element ```json { "element_id": 456, "id": 123, "element_type": "note", "content": "This is a note element...This is additional content to append to the existing content.", "note_type": "text", "color": "blue", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-08T10:15:30Z" } ``` ### Bulk #### Fields ##### Bulk update ## Description Update fields on multiple cases at once. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ----------------------------------- | | case_ids | An array of case IDs to update. | | fields | An array of field objects to apply. | | Field Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | input_id | The ID of the case input to use with the field. | | value | The value of the field. | | upsert | **Optional** By default, only cases already associated with this field are updated. Set to true to add the field to cases that don't have it. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/bulk/fields \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "case_ids": [42, 43, 44], "fields": [ { "input_id": 1, "value": "High", "upsert": true }, { "input_id": 2, "value": "Security Team" } ] }' ``` ## Response A successful request will return a JSON object with the updated cases and their fields. ### Field description | Parameter | Description | | --------- | --------------------------------- | | cases | An array of updated case objects. | | Case object | Description | | ----------- | --------------------------------- | | case_id | The ID of the case. | | fields | An array of fields for this case. | | Field object | Description | | ------------ | ------------------------------------------------------- | | id | The field ID. | | value | The value of the field. | | case_input | An object containing the ID and name of the case input. | ### Sample response ```json { "cases": [ { "case_id": 42, "fields": [ { "id": 1, "value": "High", "case_input": { "id": 1, "name": "Priority" } }, { "id": 2, "value": "Security Team", "case_input": { "id": 2, "name": "Assigned Team" } } ] }, { "case_id": 43, "fields": [ { "id": 3, "value": "High", "case_input": { "id": 1, "name": "Priority" } }, { "id": 4, "value": "Security Team", "case_input": { "id": 2, "name": "Assigned Team" } } ] }, { "case_id": 44, "fields": [ { "id": 5, "value": "High", "case_input": { "id": 1, "name": "Priority" } }, { "id": 6, "value": "Security Team", "case_input": { "id": 2, "name": "Assigned Team" } } ] } ] } ``` ### Case inputs #### Create ## Description Creates a case input on a team. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | name | The name of the case input. | | input_type | The type of the case input. One of `string`, `number`, `boolean`, or `timestamp`. | | team_id | The ID of the team where the case input should be added. | | sensitive | **Optional** A boolean (`true` or `false`) indicating whether the sensitive field permission is required to read or write this field. | | validation_type | **Optional** The validation type for the case input. One of `options` or `regex`. Use these only with `string` inputs. | | validation_options | **Optional** Validation options for the case input. For `options`, provide an array of values. For `regex`, provide a regex pattern string. | | group_name | **Optional** The name of the group to assign the case input to. | ### Sample request ```bash curl -X POST \ https:///api/v1/case_inputs/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "Operating system", "input_type": "string", "team_id": 1, "sensitive": false, "validation_type": "options", "validation_options": { "options": [ "Windows", "MacOS", "Linux" ] } }' ``` ```bash curl -X POST \ https:///api/v1/case_inputs/ \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "IP address", "input_type": "string", "team_id": 1, "sensitive": true, "validation_type": "regex", "validation_options": { "regex": "^((25[0-5]|(2[0-4]|1\\d|[1-9]|)\\d)\\.?\\b){4}$" } }' ``` ## Response A successful request will return a JSON object describing the case input. ### Field description | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | | id | The case input ID. | | name | The name of the case input. | | input_type | The type of the case input. | | sensitive | A boolean (`true` or `false`) indicating whether the sensitive field permission is required to read or write this field. | | validation_type | Validation type of the case input. | | validation_options | Validation options of the case input. | | team | An object containing the ID and name of the team the case input belongs to. | | team_case_input_group | An object containing the name of the group the case input belongs to, if any. | | created_at | An ISO 8601 timestamp representing when the case input was created. | | updated_at | An ISO 8601 timestamp representing when the case input was last updated. | ### Sample response ```json { "id": 21405, "name": "Operating system", "input_type": "string", "sensitive": false, "validation_type": "options", "validation_options": { "options": ["Windows", "MacOS", "Linux"] }, "team": { "id": 1, "name": "Engineering" }, "created_at": "2022-06-24T08:35:21Z", "updated_at": "2022-06-24T08:35:21Z" } ``` #### Get ## Description Returns a case input. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------- | | case_input_id | The ID of the case input to retrieve. | ```bash curl -X GET \ https:///api/v1/case_inputs/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful response will return a JSON object representing the specified case input. ### Field description | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | id | The case input ID. | | name | The name of the case input. | | key | The lookup key of the case input. | | input_type | The type of the case input. | | sensitive | A boolean (`true` or `false`) indicating whether the sensitive field permission is required to read or write this field. | | validation_type | The validation type of the case input. One of `none`, `options`, or `regex`. | | validation_options | An object containing validation configuration. For `options` type, contains an `options` array of accepted string values. | | team | An object containing the ID and name of the team the case input belongs to. | | team_case_input_group | An object containing the name of the group the case input belongs to, if any. | | created_at | An ISO 8601 timestamp representing when the case input was created. | | updated_at | An ISO 8601 timestamp representing when the case input was last updated. | ### Sample response ```json { "case_input": { "id": 19990840, "name": "Priority", "key": "priority", "input_type": "string", "sensitive": false, "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] }, "team": { "id": 1, "name": "Engineering Team" }, "created_at": "2022-06-24T08:35:21Z", "updated_at": "2022-06-24T08:35:21Z" } } ``` #### List ## Description Returns a list of case inputs. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | team_id | **Optional** Only include inputs from a specific team. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/case_inputs?team_id=<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful response will return a list of case inputs. ### Field description | Parameter | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | | id | The case input ID. | | name | The name of the case input. | | key | The lookup key of the case input. | | input_type | The type of the case input. | | sensitive | A boolean (`true` or `false`) indicating whether the sensitive field permission is required to read or write this field. | | validation_type | The validation type of the case input. One of `none`, `options`, or `regex`. | | validation_options | An object containing validation configuration. For `options` type, contains an `options` array of accepted string values. | | team | An object containing the ID and name of the team the case input belongs to. | | team_case_input_group | An object containing the name of the group the case input belongs to, if any. | | created_at | An ISO 8601 timestamp representing when the case input was created. | | updated_at | An ISO 8601 timestamp representing when the case input was last updated. | ### Sample response ```json { "case_inputs": [ { "id": 19990840, "name": "Priority", "key": "priority", "input_type": "string", "sensitive": false, "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] }, "team": { "id": 1, "name": "Engineering Team" }, "created_at": "2022-06-24T08:35:21Z", "updated_at": "2022-06-24T08:35:21Z" } ], "meta": { "current_page": "https://tenant.tines.io/api/v1/case_inputs?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Fields ##### List ## Description Returns a list of fields for a case input. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | case_input_id | The ID of the case input that the fields belong to. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/case_inputs/<>/fields \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request returns a JSON array describing fields for the case input. ### Field description | Parameter | Description | | ---------- | --------------------------------------------------------------------------------------------- | | id | The field ID. | | value | The stored value. | | case | An object containing the ID of the case. | | case_input | An object containing the ID, name, validation_type, and validation_options of the case input. | ### Sample response ```json { "fields": [ { "id": 1, "value": "high", "case": { "id": 1 }, "case_input": { "id": 1, "name": "Priority", "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] } } }, { "id": 2, "value": "value 2", "case": { "id": 2 }, "case_input": { "id": 2, "name": "Input #2", "validation_type": "none", "validation_options": {} } } ], "meta": { "current_page": "https:///api/v1/case_inputs/1/fields?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 } } ``` ### Comments #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Add a comment to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | value | The value of the comment to be added to the case. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | author_email | **Optional** The email of the user commenting on the case. | | Path Parameter | Description | | -------------- | -------------- | | case_id | ID of the case | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/comments \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "This is a comment on a case" }' ``` ## Response A successful request will return a JSON object describing the updated case ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | action | The action taken on the case - `commented` in this instance. | | value | The comment being added. | | user | Details of the user who created the comment - id, first & last name, email & avatar url. | | reactions | An array of objects describing the reactions and their reactants on the comment. | ### Sample response ```json { "case_id": 42, "id": 7508, "action": "COMMENTED", "value": "This is a comment", "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` #### Create ## Description Add a comment to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | value | The value of the comment to be added to the case. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | author_email | **Optional** The email of the user commenting on the case. If the specified user is not assigned to the team, the author will fallback to the API key info. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/comments \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "This is a comment on a case" }' ``` ## Response A successful request will return a JSON object describing the updated case ### Field description | Parameter | Description | | ------------- | -------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the record with the comment attached to the case. | | activity_type | The type of activity taken on the case - `commented` in this instance. | | value | The comment being added. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "activity_type": "COMMENTED", "value": "This is a comment", "created_at": "2024-03-07T11:42:58Z", "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` #### Get ## Description Retrieve a single comment for a case. ## Request HTTP Method: **GET** | Parameter | Description | | ---------- | ---------------------- | | case_id | The ID of the case. | | comment_id | The ID of the comment. | ```bash curl -X GET \ https:///api/v2/cases/<>/comments/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object of the comment. ### Field description | Parameter | Description | | ------------- | -------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | activity_type | The type of activity taken on the case - `commented` in this instance. | | value | The comment being added. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "activity_type": "COMMENTED", "value": "This is a comment", "created_at": "2024-03-07T11:42:58Z", "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` #### Update | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Update an existing case comment. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ------------------------------ | | value | The value of the case comment. | | Path Parameter | Description | | -------------- | ------------------ | | case_id | ID of the case. | | comment_id | ID of the comment. | ### Sample request ```bash curl -X PUT \ https:///api/v1/cases/<>/comments/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "This is an updated comment" }' ``` ## Response A successful request will return a JSON object describing the updated case comment. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | action | The action taken on the case - `commented` in this instance. | | value | The updated case comment. | | user | Details of the user who created the comment - id, first & last name, email & avatar url. | | reactions | An array of objects describing the reactions and their reactants on the comment. | ### Sample response ```json { "case_id": 42, "id": 7508, "action": "COMMENTED", "value": "This is an updated comment", "user": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` #### Update ## Description Update an existing case comment. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ------------------------------ | | value | The value of the case comment. | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | The ID of the case. | | comment_id | The ID of the comment. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/comments/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "This is an updated comment" }' ``` ## Response A successful request will return a JSON object describing the updated case comment. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the record with the comment attached to the case. | | action | The action taken on the case - `commented` in this instance. | | value | The updated case comment. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "activity_type": "COMMENTED", "value": "This is an updated comment", "created_at": "2024-03-07T11:42:58Z", "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` #### List ## Description Retrieve a list of comments for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/comments \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the comments. ### Field description | Parameter | Description | | --------- | ------------------------------------ | | case_id | The case ID. | | comments | An array of comments on to the case. | | Comments parameter | Description | | ------------------ | -------------------------------------------------------------------------------- | | id | The ID of the record with the comment attached to the case. | | activity_type | The type of activity taken on the case - `commented` in this instance. | | value | The comment being added. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "comments": [ { "id": 7508, "activity_type": "COMMENTED", "value": "This is a comment", "created_at": "2024-03-07T11:42:58Z", "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ], "meta": { "current_page": "https:///api/v2/cases/42/comments?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Delete a comment from a case. Comments can only be deleted by the original comment author or an admin. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ------------------ | | case_id | ID of the case. | | comment_id | ID of the comment. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/comments/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Delete a comment from a case. Comments can only be deleted by the original comment author or an admin. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ---------------------- | | case_id | The ID of the case. | | comment_id | The ID of the comment. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/comments/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Reactions ##### Add a reaction | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Add a reaction to a comment. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | | value | The value of the reaction to be added to the comment (supported reaction values: `+1`, `-1`, `eyes`, `heart`, `white_check_mark`). | | Path Parameter | Description | | -------------- | ----------------- | | case_id | ID of the case | | comment_id | ID of the comment | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/comments/<>/add_reaction \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "heart" }' ``` ## Response A successful request will return a JSON object describing the updated comment with the reaction added for the authenticated user. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | action | The action taken on the case - `commented` in this instance. | | value | The comment's value. | | user | Details of the user who created the comment - id, first & last name, email & avatar url. | | reactions | An array of objects describing the reactions and their reactants on the comment. | ### Sample response ```json { "case_id": 42, "id": 126, "action": "COMMENTED", "value": "Comment value", "user": { "user_id": "1", "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "avatar_url": "https://lh3.googleusercontent.com/a/QslEzz3Af-SGcswUnWBH7Fw-FKOAA=s96-c" }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` ##### Add a reaction ## Description Add a reaction to a comment. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | | value | The value of the reaction to be added to the comment (supported reaction values: `+1`, `-1`, `eyes`, `heart`, `white_check_mark`). | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | The ID of the case. | | comment_id | The ID of the comment. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/comments/<>/add_reaction \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "heart" }' ``` ## Response A successful request will return a JSON object describing the updated comment with the reaction added for the authenticated user. ### Field description | Parameter | Description | | ------------- | -------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | activity_type | The type of activity taken on the case - `commented` in this instance. | | value | The comment being added. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 126, "action": "COMMENTED", "value": "Comment value", "created_at": "2024-03-07T11:42:58Z", "user": { "user_id": "1", "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "avatar_url": "https://lh3.googleusercontent.com/a/QslEzz3Af-SGcswUnWBH7Fw-FKOAA=s96-c", "is_service_account": false }, "reactions": [ { "emoji": ":heart:", "reactants": [ { "user_id": 1, "user_name": "John Smith", "reacted_at": "2024-03-12T10:06:38+00:00" } ] } ] } ``` ##### Remove a reaction | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Remove a reaction from a comment. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | value | The value of the reaction to be removed from the comment. (supported reaction values: `+1`, `-1`, `eyes`, `heart`, `white_check_mark`). | | Path Parameter | Description | | -------------- | ----------------- | | case_id | ID of the case | | comment_id | ID of the comment | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/comments/<>/remove_reaction \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "heart" }' ``` ## Response A successful request will return a JSON object describing the updated comment with the specified reaction removed for the authenticated user. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | action | The action taken on the case - `commented` in this instance. | | value | The comment's value. | | user | Details of the user who created the comment - id, first & last name, email & avatar url. | | reactions | An array of objects describing the reactions and their reactants on the comment. | ### Sample response ```json { "case_id": 42, "id": 126, "action": "COMMENTED", "value": "Comment value", "user": { "user_id": "1", "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "avatar_url": "https://lh3.googleusercontent.com/a/QslEzz3Af-SGcswUnWBH7Fw-FKOAA=s96-c" }, "reactions": [] } ``` ##### Remove a reaction ## Description Remove a reaction from a comment. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | value | The value of the reaction to be removed from the comment. (supported reaction values: `+1`, `-1`, `eyes`, `heart`, `white_check_mark`). | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | The ID of the case. | | comment_id | The ID of the comment. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/comments/<>/remove_reaction \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "heart" }' ``` ## Response A successful request will return a JSON object describing the updated comment with the specified reaction removed for the authenticated user. ### Field description | Parameter | Description | | ------------- | -------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the comment attached to the case. | | activity_type | The type of activity taken on the case - `commented` in this instance. | | value | The comment being added. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 126, "action": "COMMENTED", "value": "Comment value", "created_at": "2024-03-07T11:42:58Z", "user": { "user_id": "1", "first_name": "John", "last_name": "Smith", "email": "john.smith@example.com", "avatar_url": "https://lh3.googleusercontent.com/a/QslEzz3Af-SGcswUnWBH7Fw-FKOAA=s96-c", "is_service_account": false }, "reactions": [] } ``` ### Fields #### Create ## Description Add a field to a case. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------------------------------------- | | input_id | The ID of the case input to the used with the field. | | value | The value of the field. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/fields \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "input_id": 1, "value": "This is a field on a case" }' ``` ## Response A successful request will return a JSON object describing the updated case ### Field description | Parameter | Description | | --------- | --------------------- | | case_id | The ID of the case. | | field | Details of the field. | | Field parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------- | | id | The field ID. | | value | The value of the field. | | case_input | An object containing the ID, name, key, validation_type, and validation_options of the case input. | ### Sample response ```json { "case_id": 42, "field": { "id": 1, "value": "high", "case_input": { "id": 1, "key": "priority", "name": "Priority", "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] } } } } ``` #### Get ## Description Retrieve a single field for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | -------------------- | | case_id | The ID of the case. | | field_id | The ID of the field. | ```bash curl -X GET \ https:///api/v2/cases/<>/fields/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object of the field. ### Field description | Parameter | Description | | --------- | --------------------- | | case_id | The case ID. | | field | Details of the field. | | Field parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------- | | id | The field ID. | | value | The value of the field. | | case_input | An object containing the ID, name, key, validation_type, and validation_options of the case input. | ### Sample response ```json { "case_id": 42, "field": { "id": 1, "value": "high", "case_input": { "id": 1, "key": "priority", "name": "Priority", "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] } } } } ``` #### Update ## Description Update an existing case field. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ---------------------------- | | value | The value of the case field. | | Path Parameter | Description | | -------------- | -------------------- | | case_id | The ID of the case. | | field_id | The ID of the field. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/fields/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "value": "This is an updated field" }' ``` ## Response A successful request will return a JSON object describing the updated case field. ### Field description | Parameter | Description | | --------- | --------------------- | | case_id | The ID of the case. | | field | Details of the field. | | Field parameter | Description | | --------------- | -------------------------------------------------------------------------------------------------- | | id | The field ID. | | value | The value of the field. | | case_input | An object containing the ID, name, key, validation_type, and validation_options of the case input. | ### Sample response ```json { "case_id": 42, "field": { "id": 1, "value": "high", "case_input": { "id": 1, "key": "priority", "name": "Priority", "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] } } } } ``` #### List ## Description Retrieve a list of fields for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/fields \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the fields. ### Field description | Parameter | Description | | --------- | ---------------------------------- | | case_id | The case ID. | | fields | An array of fields on to the case. | | Fields parameter | Description | | ---------------- | -------------------------------------------------------------------------------------------------- | | id | The field ID. | | value | The value of the field. | | case_input | An object containing the ID, name, key, validation_type, and validation_options of the case input. | ### Sample response ```json { "case_id": 42, "fields": [ { "id": 7508, "value": "high", "case_input": { "id": 1, "key": "priority", "name": "Priority", "validation_type": "options", "validation_options": { "options": ["low", "medium", "high", "critical"] } } } ], "meta": { "current_page": "https:///api/v2/cases/42/fields?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete ## Description Delete a field from a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | -------------------- | | case_id | The ID of the case. | | field_id | The ID of the field. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/fields/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. ### Files #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Attach a file to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filename | The name of the file to be added to the case. | | file_contents | Base64 encoded file contents to attach to the case. | | value | **Optional** The value of the comment to be added to the case. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | author_email | **Optional** The email of the user attaching the file to the case. | | team_case_block_id | **Optional** The ID of the file block to attach the file to. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/files \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "filename": "Name of file", "file_contents": "QmFzZTY0IGVuY29kZWQgZlsZSBjb250ZW50cw==", "value": "This is a comment alongside a file attachment.", "team_case_block_id": 42 }' ``` ## Response A successful request will return a JSON object describing the action taken on the case - file_attached in this instance. ### Field description | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------- | | case_id | The case ID. | | id | The ID of the record with the file attached to the case. | | action | The action taken on the case - `file_attached` or `file_attached_and_commented` in this instance. | | value | The comment added alongside file. | | user | Details of the user who attached the file - id, first & last name, email & avatar url. | | block_id | **Optional** The ID of the block the file was attached to, if a block ID was specified. | ### Sample response ```json { "case_id": 42, "id": 7508, "action": "FILE_ATTACHED_AND_COMMENTED", "value": "This is a comment alongside a file", "user": { "id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" }, "block_id": "42" } ``` #### Create ## Description Attach a file to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filename | The name of the file to be added to the case. | | file_contents | Base64 encoded file contents to attach to the case. | | value | **Optional** The value of the comment to be added to the case. Supports markdown and mentioning users. To mention a user, use the notation <@user-2435>, replacing '2435' with the user ID. | | author_email | **Optional** The email of the user attaching the file to the case. | | team_case_block_id | **Optional** The ID of the file block to attach the file to. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/files \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "filename": "Name of file", "file_contents": "QmFzZTY0IGVuY29kZWQgZlsZSBjb250ZW50cw==", "value": "This is a comment alongside a file attachment.", "team_case_block_id": 42 }' ``` ## Response A successful request will return a JSON object describing the activity taken on the case - file_attached in this instance. ### Field description | Parameter | Description | | ------------- | ----------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the record with the file attached to the case. | | activity_type | The type of activity taken on the case - `file_attached` or `file_attached_and_commented` in this instance. | | value | The comment added alongside file. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | block_id | **Optional** The ID of the block the file was attached to, if a block ID was specified. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "activity_type": "FILE_ATTACHED_AND_COMMENTED", "value": "This is a comment alongside a file", "created_at": "2024-03-25T15:40:39Z", "file": { "filename": "hello.txt", "url": "http:///api/v2/cases/42/files/7508/download" }, "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false }, "block_id": "42" } ``` #### Get ## Description Retrieve details for a case file. > **Note**: To get file metadata only, use the `/info` endpoint. To download the file contents, use the `/download` endpoint. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------ | | case_id | The ID of the case. | | file_id | The ID of the case file. | ```bash curl -X GET \ https:///api/v2/cases/<>/files/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the details for a case file. ### Field description | Parameter | Description | | ------------- | ----------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the record with the file attached to the case. | | activity_type | The type of activity taken on the case - `file_attached` or `file_attached_and_commented` in this instance. | | value | The comment added alongside file. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "activity_type": "FILE_ATTACHED_AND_COMMENTED", "value": "This is a comment alongside a file", "created_at": "2024-03-25T15:40:39Z", "file": { "filename": "hello.txt", "url": "http:///api/v2/cases/42/files/7508/download" }, "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ``` #### List ## Description Retrieve a list of files for a case. > **Note**: Each file includes a download URL. To get file metadata only, use the `/info` endpoint. To download the file contents, use the `/download` endpoint. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/files \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the details of the files for a case. ### Field description | Parameter | Description | | --------- | --------------------------------- | | case_id | The case ID. | | files | An array of files on to the case. | | Files parameter | Description | | --------------- | ----------------------------------------------------------------------------------------------------------- | | id | The ID of the record with the comment attached to the case. | | activity_type | The type of activity taken on the case - `file_attached` or `file_attached_and_commented` in this instance. | | value | The comment added alongside file. | | created_at | ISO 8601 Timestamp representing creation date. | | user | Details of the user. | | reactions | An array of objects describing the reactions and their reactants on the comment. | | User parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "files": [ { "id": 7508, "activity_type": "FILE_ATTACHED_AND_COMMENTED", "value": "This is a comment alongside a file", "created_at": "2024-03-25T15:40:39Z", "file": { "filename": "hello.txt", "url": "http:///api/v2/cases/42/files/7508/download" }, "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ], "meta": { "current_page": "https:///api/v2/cases/42/comments?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Delete a file from a case. Files can only be deleted by the user who uploaded the file or an admin. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | | file_id | ID of the file. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/files/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Delete a file from a case. Files can only be deleted by the user who uploaded the file or an admin. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | | file_id | The ID of the file. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/files/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Download ##### Get ## Description Retrieve a case file attachment. This endpoint returns the file contents for any supported file type. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ------------------------ | | case_id | The ID of the case. | | file_id | The ID of the case file. | ```bash curl -X GET \ https:///api/v2/cases/<>/files/<>/download \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the file contents with appropriate headers: **Note**: To get file metadata only (without contents), use the `/info` endpoint instead. - **Content-Type**: Set to the file's MIME type - **Content-Disposition**: - `inline` for image files (jpg, jpeg, png, gif, bmp, svg, webp, avif, apng) - `attachment` for all other file types - **Content-Security-Policy**: Prevents script execution in downloaded files A successful request using a Tines HTTP action will return a case file as JSON: ### Field description | Parameter | Description | | --------------------- | ------------------------------------- | | filename | The name of the file. | | content_type | The content type of the file. | | guid | The guid of the file. | | md5 | The md5 hash of the file. | | sha56 | The sha56 of the file. | | sizeinbytes | The file size in bytes. | | base64encodedcontents | Base 64 encoded contents of the file. | | path | The file path (guid). | ### Sample response ```json { "filename": "file", "content_type": "image/png", "guid": "78e03fc8-98cc-45dd-bf48-5a512fce6919", "md5": "112cb817c59986e29de77744b3052b65", "sha256": "807bd48b3c00aa05b0312410329c4a69c1559b1477cd17b9433e2b990f9b66b5", "sizeinbytes": 355, "base64encodedcontents": "iVBORw0KGgoANSUhEUgAABkAVO9K5CII=", "path": "ecfe3731-252d-48ba-8754-011fd12a9f71" } ``` #### Info ##### Get ## Description Retrieve metadata for a case file attachment. This endpoint returns file information without the file contents. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ------------------------ | | case_id | The ID of the case. | | file_id | The ID of the case file. | ```bash curl -X GET \ https:///api/v2/cases/<>/files/<>/info \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return the file metadata as JSON. ### Field description | Parameter | Description | | ------------ | ----------------------------- | | filename | The name of the file. | | content_type | The content type of the file. | | guid | The signed ID of the file. | | md5 | The MD5 hash of the file. | | sha256 | The SHA256 hash of the file. | | sizeinbytes | The file size in bytes. | ### Sample response ```json { "filename": "example.txt", "content_type": "text/plain", "guid": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdz09IiwiZXhwIjpudWxsLCJwdXIiOiJjb25maWd1cmF0aW9uX2tleSJ9fQ==", "md5": "d41d8cd98f00b204e9800998ecf8427e", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "sizeinbytes": 0 } ``` ### Linked cases #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Link two cases together by creating a new case link. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------- | | id | ID of the target case. | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | ID of the source case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/linked_cases \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "id": "43" }' ``` ## Response A successful request will return a JSON object of the source case with linked cases ### Field description | Parameter | Description | | ------------ | -------------------------------------- | | case_id | The case ID. | | name | The case name. | | linked_cases | An array of cases linked to this case. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "linked_cases": [ { "case_id": 43, "name": "Suspicious login detected #2" } ] } ``` #### Create ## Description Link two cases together by creating a new case link. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------- | | id | ID of the target case. | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | ID of the source case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/linked_cases \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "id": "43" }' ``` ## Response A successful request will return a JSON object of the source case with the linked case. ### Field description | Parameter | Description | | ----------- | --------------------------------------------------------------------- | | case_id | The case ID. | | name | The case name. | | linked_case | An array of cases linked to this case. Includes the case id and name. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "linked_case": { "case_id": 43, "name": "Suspicious login detected #2" } } ``` #### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve the linked cases for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------- | | case_id | The ID of the case. | ```bash curl -X GET \ https:///api/v1/cases/<>/linked_cases \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the linked cases. ### Field description | Parameter | Description | | ------------ | -------------------------------------- | | case_id | The case ID. | | name | The case name. | | linked_cases | An array of cases linked to this case. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "linked_cases": [ { "case_id": 43, "name": "Suspicious login detected #2" } ] } ``` #### List ## Description Retrieve the linked cases for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/linked_cases \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the linked cases. ### Field description | Parameter | Description | | ------------ | ------------------------------------------------------------------ | | case_id | The ID of the case. | | name | The case name. | | linked_cases | An array of cases linked to this case. Including case ID and name. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "linked_cases": [ { "case_id": 43, "name": "Suspicious login detected #2" } ], "meta": { "count": 1, "current_page": "https:///api/v2/cases/42/linked_cases?per_page=20&page=1", "next_page": null, "next_page_number": null, "pages": 1, "per_page": 20, "previous_page": null } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Unlink two cases by deleting a case link. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ---------------------- | | case_id | ID of the case. | | linked_case_id | ID of the linked case. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/linked_cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Unlink two cases by deleting a case link. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ---------------------- | | case_id | ID of the case. | | linked_case_id | ID of the linked case. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/linked_cases/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Batch create ## Description Batch link cases together by creating a new case link. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | --------------------------------------------------- | | ids | Array of IDs of the target cases. Max length of 50. | | Path Parameter | Description | | -------------- | ---------------------- | | case_id | ID of the source case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/linked_cases/batch \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "ids": ["43", "54", "67"] }' ``` ## Response A successful request will return a JSON object of the source case ID & name with the linked cases. ### Field description | Parameter | Description | | ------------ | ---------------------------------------------------------------------- | | case_id | The case ID. | | name | The case name. | | linked_cases | The array of cases linked to this case. Includes the case id and name. | ### Sample response ```json { "case_id": 42, "name": "Suspicious login detected", "linked_cases": [ { "case_id": 43, "name": "Suspicious login detected #2" }, { "case_id": 54, "name": "Suspicious login detected #3" }, { "case_id": 67, "name": "Suspicious login detected #4" } ] } ``` ### Metadata #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Create new metadata key-value pairs for a specified case. If other metadata key-value pairs already exist on the case, this does not overwrite the existing values. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ----------------------------------------------------- | | metadata | Case related metadata represented as key-value pairs. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "metadata": { "new_key": "value" } }' ``` ## Response A successful request will return a JSON object describing the updated metadata. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------- | | case_id | The case ID. | | metadata | Case related metadata represented as key-value pairs. | ### Sample response ```json { "case_id": 42, "metadata": { "new_key": "new value" } } ``` #### Create ## Description Create new metadata key-value pairs for a specified case. If other metadata key-value pairs already exist on the case, this does not overwrite the existing values. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ----------------------------------------------------- | | metadata | Case related metadata represented as key-value pairs. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "metadata": { "new_key": "value" } }' ``` ## Response A successful request will return a JSON object describing the updated metadata. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------- | | case_id | The ID of the case. | | metadata | Case related metadata represented as key-value pairs. | ### Sample response ```json { "case_id": 42, "metadata": { "new_key": "new value" } } ``` #### Get key-value pair | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a specific key-value pair from the metadata of a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------- | | case_id | The ID of the case containing metadata. | | key | The key of the key-value pair. | ```bash curl -X GET \ https:///api/v1/cases/<>/metadata/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the specific metadata key-value pair. ### Field description | Parameter | Description | | --------- | --------------------------------------------------------------------- | | case_id | The case ID. | | metadata | The case related metadata only including the specific key-value pair. | ### Sample response ```json { "case_id": 42, "metadata": { "key": "value" } } ``` #### Get key-value pair ## Description Retrieve a specific key-value pair from the metadata of a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------- | | case_id | The ID of the case containing metadata. | | key | The key of the key-value pair. | ```bash curl -X GET \ https:///api/v2/cases/<>/metadata/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the specific metadata key-value pair. ### Field description | Parameter | Description | | --------- | --------------------------------------------------------------------- | | case_id | The ID of the case. | | metadata | The case related metadata only including the specific key-value pair. | ### Sample response ```json { "case_id": 42, "metadata": { "key": "value" } } ``` #### Update | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Update existing metadata key-value pairs for a case. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ----------------------------------------------------- | | metadata | Case related metadata represented as key-value pairs. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X PUT \ https:///api/v1/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "metadata": { "key": "new value" } }' ``` ## Response A successful request will return a JSON object describing the updated metadata. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------- | | case_id | The case ID. | | metadata | Case related metadata represented as key-value pairs. | ### Sample response ```json { "case_id": 42, "metadata": { "key": "new value" } } ``` #### Update ## Description Update metadata key-value pairs for a case. You can update existing key-value pairs and create new ones if they don't already exist. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | ----------------------------------------------------- | | metadata | Case related metadata represented as key-value pairs. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "metadata": { "key": "new value" } }' ``` ## Response A successful request will return a JSON object describing the updated metadata. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------- | | case_id | The ID of the case. | | metadata | Case related metadata represented as key-value pairs. | ### Sample response ```json { "case_id": 42, "metadata": { "key": "new value" } } ``` #### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve the metadata from a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------- | | case_id | The ID of the case containing metadata. | ```bash curl -X GET \ https:///api/v1/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the metadata. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------- | | case_id | The case ID. | | metadata | Case related metadata represented as key-value pairs. | ### Sample response ```json { "case_id": 42, "metadata": { "key": "value", "second_key": "second value" } } ``` #### List ## Description Retrieve the metadata from a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------- | | case_id | The ID of the case containing metadata. | ```bash curl -X GET \ https:///api/v2/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the metadata. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------- | | case_id | The ID of the case. | | metadata | Case related metadata represented as key-value pairs. | ### Sample response ```json { "case_id": 42, "metadata": { "key": "value", "second_key": "second value" } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Delete existing metadata key-value pairs in a case. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ------------------------------------- | | metadata | A list of case related metadata keys. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "metadata": ["key", "new_key"] }' ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Delete existing metadata key-value pairs in a case. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ------------------------------------- | | metadata | A list of case related metadata keys. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/metadata \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "metadata": ["key", "new_key"] }' ``` ## Response A successful request will return an empty response with a `204` status code. ### Notes #### Create ## Description Add a note to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ------------ | --------------------------------------------------------------------------------------------------- | | title | The title of the note. | | content | **Optional** The content of the note. | | color | **Optional** The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | position | **Optional** The zero-indexed position of the note in the case. | | sensitive | **Optional** Whether the note should be excluded from exports. | | hidden | **Optional** Whether the note should be hidden (true or false). Defaults to false. | | author_email | **Optional** The email address of the author of the note. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/notes \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "title": "Note 1", "content": "This is the note content.", "position": 0, "sensitive": false, "hidden": false, "author_email": "jane@tines.io" }' ``` ## Response A successful request will return a JSON object describing the created not ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the note record attached to the case. | | title | The title of the note. | | content | The content of the note. | | author | Details of the author of the note. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | hidden | Whether the note is hidden (true or false). | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "title": "Note title", "content": "This is the note content", "color": "white", "sensitive": false, "hidden": false, "created_at": "2025-01-07T11:42:58Z", "user": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ``` #### Get ## Description Retrieve a single note for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------- | | case_id | The ID of the case. | | note_id | The ID of the note. | ```bash curl -X GET \ https:///api/v2/cases/<>/notes/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object of the note. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the note record attached to the case. | | title | The title of the note. | | content | The content of the note. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | hidden | Whether the note is hidden (true or false). | | author | Details of the author of the note. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "title": "Note title", "content": "This is a case note.", "color": "white", "hidden": false, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ``` #### Update ## Description Update an existing case note. ## Request HTTP Method: **PUT** | Parameter | Description | | ------------ | --------------------------------------------------------------------------------------------------- | | title | **Optional** The title of the case note. | | content | **Optional** The content of the case note. | | color | **Optional** The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | position | **Optional** The zero-indexed position of the note in the case. | | sensitive | **Optional** Whether the note should be excluded from exports. | | hidden | **Optional** Whether the note should be hidden (true or false). | | author_email | **Optional** The email address of the author of the note. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | | note_id | The ID of the note. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/notes/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "content": "This is an updated note.", "position": 0, "sensitive": false, "hidden": false, "author_email": "jane@tines.io" }' ``` ## Response A successful request will return a JSON object describing the updated case note. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the note record attached to the case. | | title | The title of the note. | | content | The content of the note. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | sensitive | Whether the note should be excluded from exports. | | hidden | Whether the note is hidden (true or false). | | author | Details of the author of the note. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "title": "Note title", "content": "This is an updated note.", "color": "white", "sensitive": false, "hidden": false, "created_at": "2025-01-07T11:42:58Z", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ``` #### List ## Description Retrieve a list of notes for a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/notes \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the notes. ### Field description | Parameter | Description | | --------- | -------------------------------------------- | | case_id | The ID of the case. | | notes | An array of note objects attached to a case. | | Notes Parameter | Description | | --------------- | -------------------------------------------------------------------------------------- | | id | The ID of the note record attached to the case. | | title | The title of the note. | | content | The content of the note. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | hidden | Whether the note is hidden (true or false). | | author | Details of the author of the note. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "notes": [ { "id": 7508, "title": "Note #1 title", "content": "This is the note content", "color": "white", "hidden": false, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-07T11:42:58Z", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } }, { "id": 7509, "title": "Note #2 title", "content": "This is the note content", "color": "white", "hidden": false, "created_at": "2025-01-08T11:42:58Z", "updated_at": "2025-01-08T11:42:58Z", "author": { "user_id": "1", "first_name": "John", "last_name": "Doe", "email": "john@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ] } ``` #### Delete ## Description Delete a note from a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | | note_id | The ID of the note. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/notes/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ ``` ## Response A successful request will return an empty response with a `204` status code. #### Append ## Description Append to the case note content. ## Request HTTP Method: **POST** | Parameter | Description | | ------------ | --------------------------------------------------------- | | content | The additional content of the case note. | | author_email | **Optional** The email address of the author of the note. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | | note_id | The ID of the note. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/notes/<>/content \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"content": "...This is additional content to append to the existing content."}' ``` ## Response A successful request will return a JSON object describing the updated case note. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the note record attached to the case. | | title | The title of the note. | | content | The content of the note. | | color | The color of the note - options: white, gold, magenta, green, blue, red, mint, indigo. | | sensitive | Whether the note should be excluded from exports. | | hidden | Whether the note is hidden (true or false). | | author | Details of the author of the note. | | created_at | ISO 8601 Timestamp representing creation date and time. | | updated_at | ISO 8601 Timestamp representing last updated date and time. | | Author parameter | Description | | ------------------ | ---------------------------------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | | is_service_account | Whether this user is a service account (true/false). | ### Sample response ```json { "case_id": 42, "id": 7508, "title": "Note title", "content": "This is a note....This is additional content to append to the existing content.", "color": "white", "sensitive": false, "hidden": false, "created_at": "2025-01-07T11:42:58Z", "updated_at": "2025-01-08T06:21:39Z", "author": { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar", "is_service_account": false } } ``` ### Pdf #### Get ## Description Retrieve a PDF of a case. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ```bash curl -X GET \ https:///api/v2/cases/<>/pdf \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a pdf of the case. ### Field description | Parameter | Description | | --------------------- | ------------------------------------- | | filename | The name of the file. | | content_type | The content type of the file. | | guid | The guid of the file. | | md5 | The md5 hash of the file. | | sha56 | The sha56 of the file. | | sizeinbytes | The file size in bytes. | | base64encodedcontents | Base 64 encoded contents of the file. | | path | The file path (guid). | ### Sample response ```json { "filename": "file", "content_type": "application/pdf", "guid": "78e03fc8-98cc-45dd-bf48-5a512fce6919", "md5": "112cb817c59986e29de77744b3052b65", "sha256": "807bd48b3c00aa05b0312410329c4a69c1559b1477cd17b9433e2b990f9b66b5", "sizeinbytes": 1355, "base64encodedcontents": "iVBORw0KGgoANSUhEUgAABkAVO9K5CII=", "path": "pdf" } ``` ### Records #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Add an existing record to a case. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------------------------- | | record_id | The ID of the record to add to the case. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/records \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "record_id": 423 }' ``` ## Response A successful request will return a JSON object including the case and record id. ### Field description | Parameter | Description | | --------- | ----------------------------------------- | | case_id | The case ID that the record was added to. | | record_id | The record ID. | ### Sample response ```json { "case_id": 1, "record_id": 423 } ``` #### Create ## Description Add an existing record to a case. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | ---------------------------------------- | | record_id | The ID of the record to add to the case. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/records \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "record_id": 423 }' ``` ## Response A successful request will return a JSON object including the case and record id. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------- | | case_id | The ID of the case that the record was added to. | | record | The record attached to the case. See the table below for more details. | | Records parameter | Description | | ----------------- | ------------------------------------------------------------------ | | id | The record ID. | | record_type | The record type. Includes id and name. | | records | An array of record fields. Includes the field id, name, and value. | | created_at | The timestamp the record was created. | ### Sample response ```json { "case_id": 1, "record": { "id": 423, "record_type": { "id": 1, "name": "Alert" }, "records": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ], "created_at": "2023-12-18T22:29:22Z" } } ``` #### Get | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a single record attached to a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------------------ | | case_id | The ID of the case. | | record_id | The ID of the record attached to the case. | ```bash curl -X GET \ https:///api/v1/cases/<>/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object of the record. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------- | | case_id | The case ID. | | record | The record attached to the case. See the table below for more details. | | Records parameter | Description | | ----------------- | ------------------------------------------------------------------ | | id | The record ID. | | record_type | The record type. Includes id and name. | | records | An array of record fields. Includes the field id, name, and value. | | created_at | The timestamp the record was created. | ### Sample response ```json { "case_id": 42, "record": { "id": 187, "record_type": { "id": 1, "name": "Alert" }, "records": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ], "created_at": "2023-12-18T22:29:22Z" } } ``` #### Get ## Description Retrieve a single record attached to a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------------------ | | case_id | The ID of the case. | | record_id | The ID of the record attached to the case. | ```bash curl -X GET \ https:///api/v2/cases/<>/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object of the record. ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------- | | case_id | The ID of the case. | | record | The record attached to the case. See the table below for more details. | | Records parameter | Description | | ----------------- | ------------------------------------------------------------------ | | id | The record ID. | | record_type | The record type. Includes id and name. | | records | An array of record fields. Includes the field id, name, and value. | | created_at | The timestamp the record was created. | ### Sample response ```json { "case_id": 42, "record": { "id": 187, "record_type": { "id": 1, "name": "Alert" }, "records": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ], "created_at": "2023-12-18T22:29:22Z" } } ``` #### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a list of records attached to a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/cases/<>/records \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the records. ### Field description | Parameter | Description | | --------- | ------------------------------------------------------------------------------- | | case_id | The case ID. | | records | An array of records attached to the case. See the table below for more details. | | Records parameter | Description | | ----------------- | ------------------------------------------------------------------ | | id | The record ID. | | record_type | The record type. Includes id and name. | | records | An array of record fields. Includes the field id, name, and value. | | created_at | The timestamp the record was created. | ### Sample response ```json { "case_id": 42, "records": [ { "id": 187, "record_type": { "id": 1, "name": "Alert" }, "records": [ { "id": 1871, "name": "Story name", "value": "Cases API" } ], "created_at": "2023-12-18T22:29:22Z" } ], "meta": { "current_page": "https:///api/v1/cases/42/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### List ## Description Retrieve a list of records attached to a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/records \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the records. ### Field description | Parameter | Description | | --------- | ------------------------------------------------------------------------------- | | case_id | The ID of the case. | | records | An array of records attached to the case. See the table below for more details. | | Records parameter | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | id | The record ID. | | record_type | The record type. Includes id and name. | | records | An array of records associated with the case, grouped by record type. Each record result includes the field id, name, and value. | | created_at | The timestamp the record was created. | ### Sample response ```json { "case_id": 42, "records": [ { "record_type_id": 55, "record_type_name": "Record type 2", "record_type_record_results": [ { "id": 59, "results": [ { "id": 59110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 59109, "name": "Story name", "value": "Alert investigation" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 58, "results": [ { "id": 58110, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 58109, "name": "Story name", "value": "Alert investigation #1" } ], "created_at": "2024-04-16T08:02:03Z" } ] }, { "record_type_id": 54, "record_type_name": "Record type 1", "record_type_record_results": [ { "id": 56, "results": [ { "id": 56108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 56107, "name": "Story name", "value": "Alert investigation #2" } ], "created_at": "2024-04-16T08:02:03Z" }, { "id": 55, "results": [ { "id": 55108, "name": "Timestamp", "value": "2024-04-16T08:02:03Z" }, { "id": 55107, "name": "Story name", "value": "Alert investigation #3" } ], "created_at": "2024-04-16T08:02:03Z" } ] } ], "meta": { "current_page": "https:///api/v2/cases/42/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 4 } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Remove a record from a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | -------------------------------------- | | case_id | ID of the case. | | record_id | The record ID to remove from the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Remove a record from a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | -------------------------------------- | | case_id | The ID of the case. | | record_id | The record ID to remove from the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Subscribers #### Create | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Subscribe to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ---------- | ----------------------------------- | | user_email | The email of the user to subscribe. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v1/cases/<>/subscribers \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "user_email": "jane@tines.io" }' ``` ## Response A successful request will return a JSON object with the case id. ### Field description | Parameter | Description | | --------- | --------------------------------------------------------------------- | | case_id | ID of the case. | | user | User object including, ID, first name, last name, email & avatar URL. | ### Sample response ```json { "case_id": 7508, "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" } } ``` #### Create ## Description Subscribe to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ---------- | ----------------------------------- | | user_email | The email of the user to subscribe. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/subscribers \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "user_email": "jane@tines.io" }' ``` ## Response A successful request will return a JSON object with the case id. ### Field description | Parameter | Description | | --------- | --------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the case subscriber. | | user | User object including, ID, first name, last name, email & avatar URL. | ### Sample response ```json { "case_id": 7508, "id": 2, "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" } } ``` #### List | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Retrieve a list of subscribers of a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/cases/<>/subscribers \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the subscribers. ### Field description | Parameter | Description | | ----------- | ----------------------------------------- | | case_id | The case ID. | | subscribers | An array of users subscribed to the case. | | User parameter | Description | | -------------- | ------------------------- | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | ### Sample response ```json { "case_id": 42, "subscribers": [ { "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" } ], "meta": { "current_page": "https:///api/v1/cases/42/subscribers?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### List ## Description Retrieve a list of subscribers of a case. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v2/cases/<>/subscribers \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object with the subscribers. ### Field description | Parameter | Description | | ----------- | ----------------------------------------- | | case_id | The ID of the case. | | subscribers | An array of users subscribed to the case. | | Subscribers parameter | Description | | --------------------- | ------------------------------ | | id | The ID of the case subscriber. | | user_id | The user ID. | | first_name | The user's first name. | | last_name | The user's last name. | | email | The user's email address. | | avatar_url | The user's avatar url. | ### Sample response ```json { "case_id": 42, "subscribers": [ { "id": "12", "user_id": "1", "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" } ], "meta": { "current_page": "https:///api/v2/cases/42/subscribers?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete | ⚠️ Note | | --------------------------------------------------------------------------- | | This API endpoint has been deprecated, please update to the latest version. | ## Description Unsubscribe from a case. ## Request HTTP Method: **DELETE** | Parameter | Description | | ---------- | ------------------------------------- | | user_email | The email of the user to unsubscribe. | | Path Parameter | Description | | -------------- | --------------- | | case_id | ID of the case. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/cases/<>/unsubscribe \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "user_email": "jane@tines.io" }' ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete ## Description Unsubscribe from a case. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ------------------------- | | case_id | The ID of the case. | | subscriber_id | The ID of the subscriber. | ### Sample request ```bash curl -X DELETE \ https:///api/v2/cases/<>/subscribers/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Batch create ## Description Batch subscribe users to a case. ## Request HTTP Method: **POST** | Parameter | Description | | ----------- | ------------------------------------------------------------ | | user_emails | An array emails of the users to subscribe. Max length of 50. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/subscribers/batch \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "user_emails": ["jane@tines.io", "john@tines.io"] }' ``` ## Response A successful request will return a JSON object with the case id & subscribers. ### Field description | Parameter | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | case_id | The ID of the case. | | id | The ID of the case subscriber. | | subscribers | Array of users subscribed. ID of subscriber & user object including user ID, first name, last name, email & avatar URL. | ### Sample response ```json { "case_id": 7508, "subscribers": [ { "id": 1, "user": { "user_id": 1, "first_name": "Jane", "last_name": "Doe", "email": "jane@tines.io", "avatar_url": "example.com/avatar" } }, { "id": 2, "user": { "user_id": 2, "first_name": "John", "last_name": "Doe", "email": "john@tines.io", "avatar_url": "example.com/avatar" } } ] } ``` ### Tasks #### Create ## Description Create a task for a specific case. ## Request HTTP Method: **POST** | Parameter | Description | | --------------- | ----------------------------------------------------------- | | description | The task description. | | assignee_emails | **Optional** An array of user emails to assign to the task. | | Path Parameter | Description | | -------------- | ------------------------------------------ | | case_id | The ID of the case to create the task for. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/tasks \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "description": "Review security logs for suspicious activity", "assignee_emails": ["user1@example.com", "user2@example.com"] }' ``` ## Response A successful request will return a JSON object representing the created task. ### Field description | Parameter | Description | | --------- | ------------------------ | | task | The created task object. | #### Task object fields | Parameter | Description | | ----------- | -------------------------------------------------------------------------- | | id | The task ID. | | description | The task description. | | completed | Boolean indicating whether the task is completed. | | assignees | An array of users assigned to the task. | | created_at | ISO 8601 Timestamp representing the date and time the task was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the task was updated at. | #### Assignee object fields | Parameter | Description | | ---------- | ---------------------- | | id | The user ID. | | email | The user email. | | first_name | The user's first name. | | last_name | The user's last name. | ### Sample response ```json { "task": { "id": 1, "description": "Review security logs for suspicious activity", "completed": false, "assignees": [ { "id": "123", "email": "user1@example.com", "first_name": "John", "last_name": "Doe" }, { "id": "456", "email": "user2@example.com", "first_name": "Jane", "last_name": "Smith" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } } ``` #### Get ## Description Retrieve a single task from a specific case. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------- | | case_id | The ID of the case. | | task_id | The ID of the task to retrieve. | ```bash curl -X GET \ https:///api/v2/cases/<>/tasks/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified task. ### Field description | Parameter | Description | | --------- | ---------------- | | task | The task object. | #### Task object fields | Parameter | Description | | ----------- | -------------------------------------------------------------------------- | | id | The task ID. | | description | The task description. | | completed | Boolean indicating whether the task is completed. | | assignees | An array of users assigned to the task. | | created_at | ISO 8601 Timestamp representing the date and time the task was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the task was updated at. | #### Assignee object fields | Parameter | Description | | ---------- | ---------------------- | | id | The user ID. | | email | The user email. | | first_name | The user's first name. | | last_name | The user's last name. | ### Sample response ```json { "task": { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123", "email": "user1@example.com", "first_name": "John", "last_name": "Doe" }, { "id": "456", "email": "user2@example.com", "first_name": "Jane", "last_name": "Smith" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } } ``` #### Update ## Description Update a task for a specific case. ## Request HTTP Method: **PUT** | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------- | | description | **Optional** The task description. | | completed | **Optional** Boolean indicating whether the task is completed. | | assignee_emails | **Optional** An array of user emails to assign to the task. This will replace existing assignees. | | Path Parameter | Description | | -------------- | ----------------------------- | | case_id | The ID of the case. | | task_id | The ID of the task to update. | ### Sample request ```bash curl -X PUT \ https:///api/v2/cases/<>/tasks/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "description": "Review security logs for suspicious activity - Updated", "completed": true, "assignee_emails": ["user1@example.com", "user3@example.com"] }' ``` ## Response A successful request will return a JSON object representing the updated task. ### Field description | Parameter | Description | | --------- | ------------------------ | | task | The updated task object. | #### Task object fields | Parameter | Description | | ----------- | -------------------------------------------------------------------------- | | id | The task ID. | | description | The task description. | | completed | Boolean indicating whether the task is completed. | | assignees | An array of users assigned to the task. | | created_at | ISO 8601 Timestamp representing the date and time the task was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the task was updated at. | #### Assignee object fields | Parameter | Description | | ---------- | ---------------------- | | id | The user ID. | | email | The user email. | | first_name | The user's first name. | | last_name | The user's last name. | ### Sample response ```json { "task": { "id": 1, "description": "Review security logs for suspicious activity - Updated", "completed": true, "assignees": [ { "id": "123", "email": "user1@example.com", "first_name": "John", "last_name": "Doe" }, { "id": "789", "email": "user3@example.com", "first_name": "Bob", "last_name": "Johnson" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T16:25:10Z" } } ``` #### List ## Description Retrieve a list of tasks for a specific case. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | case_id | The ID of the case to retrieve tasks for. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 50. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ 'https:///api/v2/cases/<>/tasks?page=1&per_page=20' \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing an array of tasks for the specified case. ### Field description | Parameter | Description | | --------- | -------------------------------------------------- | | tasks | An array of task objects associated with the case. | | meta | Pagination metadata (see below). | #### Task object fields | Parameter | Description | | ----------- | -------------------------------------------------------------------------- | | id | The task ID. | | description | The task description. | | completed | Boolean indicating whether the task is completed. | | assignees | An array of users assigned to the task. | | created_at | ISO 8601 Timestamp representing the date and time the task was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the task was updated at. | #### Assignee object fields | Parameter | Description | | ---------- | ---------------------- | | id | The user ID. | | email | The user email. | | first_name | The user's first name. | | last_name | The user's last name. | ### Sample response ```json { "tasks": [ { "id": 1, "description": "Review security logs", "completed": false, "assignees": [ { "id": "123", "email": "user1@example.com", "first_name": "John", "last_name": "Doe" }, { "id": "456", "email": "user2@example.com", "first_name": "Jane", "last_name": "Smith" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Contact affected users", "completed": true, "assignees": [ { "id": "789", "email": "user3@example.com", "first_name": "Bob", "last_name": "Johnson" } ], "created_at": "2024-03-25T15:30:20Z", "updated_at": "2024-03-25T16:15:45Z" } ], "meta": { "current_page": "https:///api/v2/cases/1/tasks?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` #### Delete ## Description Delete a task. ## Request HTTP Method: **DELETE** | Query Parameter | Description | | --------------- | ----------------------------- | | case_id | The ID of the case. | | task_id | The ID of the task to delete. | ```bash curl -X DELETE \ https:///api/v2/cases/<>/tasks/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the ID of the deleted task. ### Field description | Parameter | Description | | ------------ | --------------------------- | | destroyed_id | The ID of the deleted task. | ### Sample response ```json { "destroyed_id": "1" } ``` #### Batch create ## Description Batch create tasks for a specific case. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | tasks | An array of task objects. Max length of 25. Each object must include a `description` and may optionally include an `assignee_emails` string array. | | Path Parameter | Description | | -------------- | ------------------- | | case_id | The ID of the case. | ### Task object fields | Parameter | Description | | --------------- | ----------------------------------------------------------- | | description | The task description. | | assignee_emails | **Optional** An array of user emails to assign to the task. | ### Sample request ```bash curl -X POST \ https:///api/v2/cases/<>/tasks/batch \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "tasks": [ { "description": "Review security logs for suspicious activity", "assignee_emails": ["user1@example.com"] }, { "description": "Update incident runbook" }, { "description": "Close related tickets", "assignee_emails": ["user2@example.com", "user3@example.com"] } ] }' ``` ## Response A successful request will return a JSON object containing an array of the created tasks. ### Field description | Parameter | Description | | --------- | --------------------------------- | | tasks | An array of created task objects. | #### Task object fields | Parameter | Description | | ----------- | -------------------------------------------------------------------------- | | id | The task ID. | | description | The task description. | | completed | Boolean indicating whether the task is completed. | | assignees | An array of users assigned to the task. | | created_at | ISO 8601 Timestamp representing the date and time the task was created at. | | updated_at | ISO 8601 Timestamp representing the date and time the task was updated at. | #### Assignee object fields | Parameter | Description | | ---------- | ---------------------- | | id | The user ID. | | email | The user email. | | first_name | The user's first name. | | last_name | The user's last name. | ### Sample response ```json { "tasks": [ { "id": 1, "description": "Review security logs for suspicious activity", "completed": false, "assignees": [ { "id": "123", "email": "user1@example.com", "first_name": "John", "last_name": "Doe" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 2, "description": "Update incident runbook", "completed": false, "assignees": [], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" }, { "id": 3, "description": "Close related tickets", "completed": false, "assignees": [ { "id": "456", "email": "user2@example.com", "first_name": "Jane", "last_name": "Smith" }, { "id": "789", "email": "user3@example.com", "first_name": "Bob", "last_name": "Wilson" } ], "created_at": "2024-03-25T15:40:39Z", "updated_at": "2024-03-25T15:40:39Z" } ] } ``` ## Records ### Create ## Description Create a new record. ## Request HTTP Method: **POST** | Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | record_type_id | Specifies the id of the record type for which the record is being created. | | field_values | This parameter is an array comprised of objects. Each object must include a `field_id`, which identifies the record field, and a `value`, specifying the data to be assigned to that field for the newly created record. | | case_ids | **Optional** Specifies the case IDs to link to this record. | | test_mode | **Optional** Boolean `true` or `false` value specifying if record being created is related to test stories. Defaults to false. | ### Field values parameter | Field values | Description | | ------------ | ---------------------------------- | | field_id | The ID of the record field. | | value | The value to set the record field. | ```bash curl -X POST \ https:///api/v1/records \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "record_type_id": "1", "field_values": [{ "field_id": "1", "value": "Test" }], "case_ids": ["14","19"] }' ``` ## Response A successful request will return a JSON object representing the created record. ### Field description | Parameter | Description | | ----------- | ------------------------------------------------------------------------- | | id | The record ID. | | record_type | The record type. | | test_mode | Boolean indicator of whether the record was created in test mode. | | records | The captured data for the given instance of the record type. | | created_at | ISO 8601 Timestamp representing the creation date and time of the record. | | case_ids | The case IDs linked to this record. | | result | The captured data in key-value format. | ### Sample response ```json { "id": 1973, "created_at": "2024-06-25T14:41:23Z", "record_type": { "id": 1097, "name": "Tines Sample Alert" }, "test_mode": false, "records": [ { "field_id": "5999", "name": "Affected user email", "value": "john@example.com" }, { "field_id": "5998", "name": "Source", "value": "Login alerts" }, { "field_id": "5997", "name": "Description", "value": "Suspicious login" }, { "field_id": "5996", "name": "Severity", "value": "High" }, { "field_id": "5991", "name": "Timestamp", "value": "2024-06-25 15:41:23" } ], "case_ids": [14, 19], "result": { "id": 1973, "Affected user email": "john@example.com", "Source": "Login alerts", "Description": "Suspicious login", "Severity": "High", "Timestamp": "2024-06-25 15:41:23", "case_ids": [14, 19], "updated_at": "2024-06-25T14:41:23Z" } } ``` ### Get ## Description Retrieve a single record. The record ID appears in the URL when viewing a record: `https:///records/types/{record_type_id}/results/{record_id}`, or in the response from the [List Records API](/api/records/list). ## Request HTTP Method: **GET** | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | record_id | The ID of the record to retrieve. | | record_type_id | **Optional** The ID of the record type. Including this parameter may result in a faster query. | | record_field_ids | **Optional** An array of record field IDs. When provided, only the specified fields are included in the response. The `id`, `updated_at`, and `case_ids` fields are always returned. | | resolve_artifacts | **Optional** Boolean `true` or `false` value. When `true`, Artifacts (large text) fields return the full contents instead of just the artifact ID. Defaults to `false`. | ```bash curl -X GET \ https:///api/v1/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` Or, for faster performance, include the record type ID: ```bash curl -X GET \ https:///api/v1/records/<>?record_type_id=<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Example request with record_field_ids To return only specific fields in the response: ```bash curl -X GET \ "https:///api/v1/records/<>?record_field_ids[]=<>&record_field_ids[]=<>" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` **Note:** All field IDs must belong to the record's record type. A `404` error is returned if any field ID does not exist, and a `422` error is returned if any field ID belongs to a different record type. ### Example request with resolve_artifacts To return full artifact contents instead of artifact IDs: ```bash curl -X GET \ "https:///api/v1/records/<>?resolve_artifacts=true" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified record. ### Artifacts (large text) By default, Artifacts (large text) field types return a reference object containing the artifact ID and an `is_artifact` flag, rather than the data itself: ```json { "id": 674623, "is_artifact": true } ``` This `id` is the `artifact_id` you need to pass to the [GET Artifacts (large text) API](https://www.tines.com/api/records/artifacts/get) endpoint to retrieve the actual contents. Alternatively, set `resolve_artifacts=true` in the request to include full artifact contents directly in the response. ### Field description | Parameter | Description | | -------------- | ---------------------------------------------------------------------------------- | | id | The record ID. | | created_at | ISO 8601 Timestamp representing creation date and time of the record. | | story | The story the record was created from. | | story_run_guid | The story run guid the record was created from. | | record_type | The the type of record the result set was created for. | | records | The captured data for the given instance of the record type. | | child_records | An array of objects containing the record IDs for which this record is the parent. | | parent_record | The ID of this record's parent record. | | case_ids | An array of case IDs linked to this record. | | result | The captured data in key-value format. | ### Sample response ```json { "id": 59, "created_at": "2023-06-14T15:09:02Z", "story": { "id": 8, "name": "Create new IOC" }, "story_run_guid": "82c8e2c8-ab56-49c9-bdb9-1ea5b7fd5b2e", "record_type": { "id": 1, "name": "Alert" }, "records": [ { "name": "Story name", "value": "Create new IOC" }, { "name": "Timestamp", "value": "2023-06-14 16:09:02" }, { "name": "Name", "value": "Example" }, { "name": "Description", "value": { "id": 674623, "is_artifact": true } } ], "child_records": [ { "id": 9 } ], "parent_record": { "id": 66 }, "case_ids": [4, 2], "result": { "id": 59, "updated_at": "2023-06-14T15:09:02Z", "case_ids": [4, 2], "Story name": "Create new IOC", "Timestamp": "2023-06-14 16:09:02", "Name": "Example", "Description": { "id": 674623, "is_artifact": true } } } ``` ### Update ## Description Updates a single record. ## Request HTTP Method: **PUT** | Parameter | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | add_child_records | **Optional** An array of record IDs to be added to the record as child records | | remove_child_records | **Optional** An array of record IDs to remove from the record as child records | | add_team_case_ids | **Optional** An array of case IDs to be linked to the record | | remove_team_case_ids | **Optional** An array of case IDs to be unlinked from the record | | field_values | **Optional** An array of objects. Each object should contain a `field_id` of the field you wish to update and a `value` for the updated value. | | Field values | Description | | ------------ | --------------------------------------- | | field_id | The ID of the field you wish to update. | | value | The value to update the field with. | | Path Parameter | Description | | -------------- | ------------------------------- | | record_id | The ID of the record to update. | ### Sample request ```bash curl -X PUT \ https:///api/v1/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "add_child_records": ["1"], "field_values": [{"field_id":"285","value":"true"}], "add_team_case_ids": ["14","19"] }' ``` ## Response A successful request will return a JSON object representing the specified record. ### Field description | Parameter | Description | | -------------- | ---------------------------------------------------------------------------------- | | id | The record ID. | | created_at | ISO 8601 Timestamp representing the creation date and time of the record. | | updated_at | ISO 8601 Timestamp representing the last update date and time of the record. | | story | The story the record was created from. | | story_run_guid | The story run guid the record was created from. | | record_type | The type of record the record was created for. | | records | The captured data for the given instance of the record type. | | child_records | An array of objects containing the record IDs for which this record is the parent. | | case_ids | The case IDs linked to this record. | | result | The captured data in key-value format. | A successful request will return a JSON object describing the updated record. ### Sample response ```json { "id": 59, "created_at": "2023-06-14T15:09:02Z", "updated_at": "2023-06-14T15:10:32Z", "story": { "id": 8, "name": "Create new IOC" }, "story_run_guid": "82c8e2c8-ab56-49c9-bdb9-1ea5b7fd5b2e", "record_type": { "id": 1, "name": "Alert" }, "records": [ { "field_id": "36", "name": "Story name", "value": "Create new IOC" }, { "field_id": "37", "name": "Timestamp", "value": "2023-06-14 16:09:02" }, { "field_id": "38", "name": "Name", "value": "Example" } ], "child_records": [ { "id": 9, "records": [ { "field_id": "39", "name": "Story name", "value": "Create new IOC" }, { "field_id": "40", "name": "Timestamp", "value": "2023-06-14 16:09:02" }, { "field_id": "41", "name": "Name", "value": "Example" } ] } ], "case_ids": [14, 19], "result": { "id": 59, "updated_at": "2023-06-14T15:10:32Z", "case_ids": [14, 19], "Story name": "Create new IOC", "Timestamp": "2023-06-14 16:09:02", "Name": "Example" } } ``` ### List ## Description Retrieve a list of records. To find the record type ID to filter against, navigate to any record page at `https:///records`. Then, click the dropdown menu at the top right and select `Copy record type ID`. Alternatively, you may find the record type ID (and field IDs) in that same menu under `Manage record type`. This information may also be retrieved from the [List Record Types API](/api/records/record_types/list). ![Copy record type ID](https://www.datocms-assets.com/55802/1764706143-copy-record-id-edited.png) ## Request HTTP Method: **GET** | Query Parameter | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | record_type_id | The ID of the record type (optional if `record_field_ids` are present). | | record_field_ids | An array of record field IDs that determines which fields (columns) are included in each record result (optional if `record_type_id` is present). When omitted and `record_type_id` is provided, all fields of the record type are returned. | | range_start | **Optional** The start time for the time range of records (ISO 8601 timestamp). | | range_end | **Optional** The end time for the time range of records (ISO 8601 timestamp). | | story_ids | **Deprecated** **Optional** An array of _internal_ story IDs to filter the results. Cannot be used with `story_container_ids`. In test mode, it translates to test story IDs. Note: this is a legacy field and does not match the IDs in the URL of a story. It matches the IDs used in the Records view. Please use `story_container_ids` to match the behavior of other endpoints that reference Story ID. | | story_container_ids | **Optional** An array of story IDs to filter the results. Cannot be used with `story_ids`. | | order_direction | **Optional** The direction to order records: `ASC` or `DESC`. Defaults to `DESC`. | | order_field_id | **Optional** The ID of the field used to order records. Supports custom fields as well as default fields such as Timestamp and Updated at. When omitted, records are ordered by creation date. | | per_page | **Optional** Set the number of records returned per page. Defaults to 20, maximum is 500. | | page | **Optional** The page number of results to fetch. | | filters | **Optional** An array of objects each specifying a record filter (see the table below). | | test_mode | **Optional** Boolean `true` or `false` value. Specify whether to filter by records created in test stories. | | parent_ids | **Optional** An array of parent record IDs. Returns only first-degree child records of the specified parent records. Use this to efficiently retrieve all children of one or more parent records. | **Important:** The `record_field_ids` parameter is different from the `field_id` used inside `filters`. The `record_field_ids` parameter controls which fields (columns) appear in each record result in the response, while `field_id` in `filters` specifies which fields to apply filter conditions to when selecting which records to return. Supported parameters in `filters` | Parameters | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | field_id | The record field (i.e. record column) id to apply the filter condition to. | | operator | `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `IS_EMPTY`, `IS_NOT_EMPTY`, `IS_TRUE`, `IS_FALSE`, `IS_ANY_OF`, or `IS_NONE_OF`. Note: `EQUAL`, `NOT_EQUAL`, `IS_ANY_OF`, and `IS_NONE_OF` are case insensitive. | | value | Depending on the operator, a string, number, or omitted. For `IS_ANY_OF` and `IS_NONE_OF` operators, provide an array of values instead of a single value. Note: `IS_ANY_OF` and `IS_NONE_OF` are only available for text, text fixed enums, and number fields. | ### Example request with search filters Sample request params: ```json { "filters": [ { "field_id": "5", "operator": "EQUAL", "value": "ALERT" } ], "record_type_id": "1", "range_end": "2023-07-03T00:00:00Z", "range_start": "2022-07-03T23:59:59Z" } ``` Example request: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?range_end=2023-07-03T00:00:00Z&range_start=2022-07-03T23:59:59Z&record_type_id=1&filters==[{"value":"ALERT","operator":"EQUAL","field_id":"5"}]" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` Tip: You can copy the cURL command of the record table and its filters you're viewing in the Tines app. ### Example request with IS_ANY_OF operator Sample request params using `IS_ANY_OF` with an array of values: ```json { "filters": [ { "field_id": "5", "operator": "IS_ANY_OF", "value": ["ALERT", "WARNING", "CRITICAL"] } ], "record_type_id": "1" } ``` Example request: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&filters=[{\"field_id\":\"5\",\"operator\":\"IS_ANY_OF\",\"value\":[\"ALERT\",\"WARNING\",\"CRITICAL\"]}]" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Example request with story_container_ids To retrieve records from specific story containers (workflows): ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&story_container_ids[]=123&story_container_ids[]=456" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` To retrieve records from test stories within story containers: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&story_container_ids[]=123&test_mode=true" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` **Note:** You cannot specify both `story_ids` and `story_container_ids` in the same request. ### Example request with parent_ids To retrieve all first-degree child records of specific parent records: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&parent_ids[]=123&parent_ids[]=456" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` To retrieve child records of a single parent: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&parent_ids[]=123" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Rate limit Please be aware that usage of this endpoint is subject to a rate limit of 400 requests per minute. ## Response A successful request will return a JSON object containing the records the requesting token has access to. ### Artifacts (large text field) Please note that Artifacts (large text) field types do not return the Artifacts data itself, but instead return a reference object containing the artifact ID and an `is_artifact` flag: ```json { "id": 674623, "is_artifact": true } ``` This `id` is the `artifact_id` you need to pass to the [GET Artifacts (large text) API](https://www.tines.com/api/records/artifacts/get) endpoint to retrieve the actual contents. ### Field description The response contains these top-level fields: | Field | Description | | -------------- | -------------------------------------------------------------------------------------- | | record_type | Object containing the record type information with `id` (integer) and `name` (string). | | record_results | Array of objects, each representing a record (see below). | | meta | Object containing pagination information. | Each object in the `record_results` array contains the following fields: | Field | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | Integer ID of the record. | | updated_at | ISO 8601 timestamp representing when the record was last updated. | | case_ids | Array of integer case IDs that this record is associated with. | | parent_record | Object with `id` (integer) for this record's parent, or `null` if this record has no parent. Same shape as [Get record](/api/records/get). | | Story name | The name of the story this record was created in. This is a default field present on every record type. | | Timestamp | The date and time the record was created. This is a default field present on every record type. | | _(other fields)_ | Each remaining key-value pair corresponds to a record field. The keys are the field names and the values are the field contents. Which fields appear depends on the `record_field_ids` parameter (or all fields if only `record_type_id` is provided). | ### Sample response ```json { "record_type": { "id": 1, "name": "Alerts" }, "record_results": [ { "Story name": "Create new issue", "Timestamp": "2023-06-06 16:18:34", "Alert": "High", "updated_at": "2023-06-06T16:18:34Z", "case_ids": [1, 2], "parent_record": null, "id": 1 }, { "Story name": "Create new issue", "Timestamp": "2023-06-13 18:13:15", "Alert": "Medium", "updated_at": "2023-06-13T18:13:15Z", "case_ids": [1], "parent_record": null, "id": 2 }, { "Story name": "Create new issue", "Timestamp": "2023-06-13 18:13:16", "Alert": "Low", "updated_at": "2023-06-13T18:13:16Z", "case_ids": [], "parent_record": null, "id": 3 } ], "meta": { "current_page": "https:///api/v1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, // Max: 500 "pages": 1, "count": 3 } } ``` ### Delete ## Description Delete a record. ## Request HTTP Method: **DELETE** | Parameter | Description | | --------- | ------------------------------- | | record_id | The ID of the record to delete. | ```bash curl -X DELETE \ https:///api/v1/records/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Artifacts #### Get ## Description Retrieve an individual record artifact (large text field). Please note that the Artifacts (large text) field types return only the ID of the Artifacts, not the data itself when using the [GET Records API](https://www.tines.com/api/records/get) or [List Records API](https://www.tines.com/api/records/list). To access the actual contents, you need to make a separate request to this endpoint using that ID as the `artifact_id` parameter. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | -------------------------- | | record_id | ID of the record. | | artifact_id | ID of the record artifact. | ```bash curl -X GET \ https:///api/v1/records/<>/artifacts/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a record artifact. ### Field description | Parameter | Description | | ------------ | ---------------------------------------------------------------------------------- | | id | The record artifact ID. | | value | The record artifact's value. | | record_field | JSON containing the id and name of the record field. | | created_at | ISO 8601 Timestamp representing the creation date and time of the record artifact. | | updated_at | ISO 8601 Timestamp representing the last updated date and time of record artifact. | ### Sample response ```json { "id": 1, "value": "artifact value", "record_field": { "id": 1, "name": "record field name" }, "created_at": "2024-02-16T15:37:39Z", "updated_at": "2024-02-16T15:37:39Z" } ``` ### Record types #### Create ## Description Create a new record type. ## Request HTTP Method: **POST** | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The record type name. | | description | **Optional** A short description of the record type. | | team_id | ID of team to which the record type belongs. | | fields | An array of objects describing the custom record fields defined by the user. | | editable | **Optional** Whether the records for this record type are editable or not. | | ttl_days | **Optional** Records for this record type will be deleted after this number of days. Accepted values: `0.25` (6 hours), `0.5` (12 hours), `1`, `2`, `3`, `7`, `14`, `30`, `60`, `90`, `180`, `365`, `548`, `730`, `1095`, `1460`, `1825`, `2190`, `2555`, `2920`, `3285`, `3650`. | | retention_column_name | **Optional** The timestamp column used to determine record age for TTL expiry. Accepted values are `CREATED_AT` (default) and `UPDATED_AT`. With `UPDATED_AT`, a record's age resets each time it's updated, so only records that haven't been updated within `ttl_days` are deleted. Has no effect unless `ttl_days` is set. | | on_limit_reached | **Optional** Behavior when the record type reaches its per-type record limit. Accepted values are `REJECT` (default; block new writes) and `EVICT_OLDEST` (delete the oldest record to make room for the new one). | | max_records_limit | **Optional** Custom per-record-type record limit. Must be a positive integer no greater than the tenant ceiling. If omitted, the tenant default applies. | ### Fields parameter The `fields` parameter is an array of objects representing the custom record fields defined by the user. Each object within this array must include a `name` property and a `result_type` property. The `result_type` property specifies the data type of the field. Acceptable values for `result_type` are: - `TEXT`: For text-based fields - `NUMBER`: For numeric fields - `TIMESTAMP`: For date and time fields - `BOOLEAN`: For true/false fields - `TEXT_ENUM`: For text fields with a predefined set of values - `ARTIFACT`: For large text fields If the `result_type` is set to `TEXT_ENUM`, an additional `fixed_values` property must be included. This property should be an array containing the allowed values for that field. ```bash curl -X POST \ https:///api/v1/record_types/ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "name": "Record type name", "description": "Optional description of the record type", "team_id": "<>", "fields": [{ "name": "Column 1", "result_type": "TEXT" }], "editable": true, "ttl_days": 3, "retention_column_name": "UPDATED_AT", "on_limit_reached": "EVICT_OLDEST", "max_records_limit": 5000 }' ``` ## Response A successful request will return a JSON object representing the created record type. ### Field description | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The record type ID. | | name | The record type name. | | description | A short description of the record type, or null if not set. | | team_id | ID of team to which the record type belongs. | | editable | Whether the records for this record type are editable or not. | | ttl_days | Records for this record type will be deleted after this number of days. | | retention_column_name | The timestamp column used to determine record age for TTL expiry. One of `CREATED_AT` or `UPDATED_AT`. With `UPDATED_AT`, a record's age resets each time it's updated. | | on_limit_reached | Behavior when the record type reaches its per-type record limit. One of `REJECT` (block new writes) or `EVICT_OLDEST` (delete the oldest record to make room). | | max_records_limit | Custom per-record-type record limit, or `null` if no custom limit is set (in which case the tenant default applies). | | record_fields | An array of objects describing the custom record fields defined by the user. | | default_record_fields | An array of objects describing the default record fields (Timestamp and Story name). | ### Sample response ```json { "id": 1, "name": "Record type 1", "description": "Optional description of the record type", "editable": false, "ttl_days": 3, "retention_column_name": "UPDATED_AT", "on_limit_reached": "EVICT_OLDEST", "max_records_limit": 5000, "record_fields": [ { "id": 1, "name": "Field 1", "result_type": "TEXT", "fixed_values": [] } ], "default_record_fields": [ { "id": 2, "name": "Story name", "result_type": "TEXT", "fixed_values": [] }, { "id": 3, "name": "Timestamp", "result_type": "TIMESTAMP", "fixed_values": [] } ] } ``` #### Get ## Description Retrieve a single record type. ## Request HTTP Method: **GET** | Parameter | Description | | -------------- | -------------------------------------- | | record_type_id | The ID of the record type to retrieve. | ```bash curl -X GET \ https:///api/v1/record_types/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified record type. ### Field description | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The record type ID. | | name | The record type name. | | description | A short description of the record type, or null if not set. | | team_id | ID of team to which the record type belongs. | | editable | Whether the records for this record type are editable or not. | | ttl_days | Records for this record type will be deleted after this number of days. | | retention_column_name | The timestamp column used to determine record age for TTL expiry. One of `CREATED_AT` or `UPDATED_AT`. With `UPDATED_AT`, a record's age resets each time it's updated. | | on_limit_reached | Behavior when the record type reaches its per-type record limit. One of `REJECT` (block new writes) or `EVICT_OLDEST` (delete the oldest record to make room). | | max_records_limit | Custom per-record-type record limit, or `null` if no custom limit is set (in which case the tenant default applies). | | record_fields | An array of objects describing the custom record fields defined by the user. | | default_record_fields | An array of objects describing the default record fields (Timestamp and Story name). | ### Sample response ```json { "id": 1, "name": "Record type 1", "description": "Optional description of the record type", "editable": true, "ttl_days": 4, "retention_column_name": "CREATED_AT", "on_limit_reached": "REJECT", "max_records_limit": null, "record_fields": [ { "id": 1, "name": "Field 1", "result_type": "TEXT", "fixed_values": [] } ], "default_record_fields": [ { "id": 2, "name": "Story name", "result_type": "TEXT", "fixed_values": [] }, { "id": 3, "name": "Timestamp", "result_type": "TIMESTAMP", "fixed_values": [] } ] } ``` #### Update ## Description Update an existing record type. You can update the record type name, editable status, TTL settings, retention column, FIFO behavior, custom record limit, and fields. ## Request HTTP Method: **PUT** | Parameter | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | record_type_id | The ID of the record type to update. | | name | **Optional** The record type name. | | description | **Optional** A short description of the record type. | | editable | **Optional** Whether the records for this record type are editable or not. | | ttl_days | **Optional** Records for this record type will be deleted after this number of days. Accepted values: `0.25` (6 hours), `0.5` (12 hours), `1`, `2`, `3`, `7`, `14`, `30`, `60`, `90`, `180`, `365`, `548`, `730`, `1095`, `1460`, `1825`, `2190`, `2555`, `2920`, `3285`, `3650`. | | retention_column_name | **Optional** The timestamp column used to determine record age for TTL expiry. Accepted values are `CREATED_AT` and `UPDATED_AT`. With `UPDATED_AT`, a record's age resets each time it's updated, so only records that haven't been updated within `ttl_days` are deleted. Has no effect unless `ttl_days` is set. Sending `null` while TTL is set returns 400. | | on_limit_reached | **Optional** Behavior when the record type reaches its per-type record limit. Accepted values are `REJECT` (block new writes) and `EVICT_OLDEST` (delete the oldest record to make room). | | max_records_limit | **Optional** Custom per-record-type record limit. Must be a positive integer no greater than the tenant ceiling. Send `null` to clear an existing custom limit and fall back to the tenant default. | | fields | **Optional** An array of objects describing the record fields. See [Fields parameter](#fields-parameter) for behavior. | | field_ids_to_delete | **Optional** An array of field IDs to delete. Use this to explicitly remove fields from the record type. | ### Fields parameter The `fields` parameter is an array of objects representing the record fields. When provided, fields included in the array are created or updated. Fields not included in the array are preserved unchanged. If the `fields` parameter is omitted, not provided, or set to `null`, all existing fields remain unchanged. Providing an empty array (`[]`) will also preserve all existing fields. To update an existing field, include its `id` along with the properties to change. To add a new field, omit the `id` and provide at least a `name` and `result_type`. To delete fields, use the `field_ids_to_delete` parameter with an array of field IDs to remove. The `result_type` property specifies the data type of the field. Acceptable values for `result_type` are: - `TEXT`: For text-based fields - `NUMBER`: For numeric fields - `TIMESTAMP`: For date and time fields - `BOOLEAN`: For true/false fields - `TEXT_ENUM`: For text fields with a predefined set of values - `ARTIFACT`: For large text fields If the `result_type` is set to `TEXT_ENUM`, an additional `fixed_values` property must be included. This property should be an array containing the allowed values for that field. The `result_type` can only be changed between `TEXT` and `TEXT_ENUM` - other data type changes are not allowed. ```bash curl -X PUT \ https:///api/v1/record_types/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated record type name" }' curl -X PUT \ https:///api/v1/record_types/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Updated record type name", "description": "Updated description of the record type", "editable": true, "ttl_days": 7, "retention_column_name": "UPDATED_AT", "on_limit_reached": "EVICT_OLDEST", "max_records_limit": 5000, "fields": [ { "id": 1, "name": "Updated Column Name", "result_type": "TEXT_ENUM", "fixed_values": ["Option A", "Option B", "Option C"] }, { "name": "New Column", "result_type": "NUMBER" } ], "field_ids_to_delete": [2, 5] }' ``` ## Response A successful request will return a JSON object representing the updated record type. ### Field description | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The record type ID. | | name | The record type name. | | description | A short description of the record type, or null if not set. | | team_id | ID of team to which the record type belongs. | | editable | Whether the records for this record type are editable or not. | | ttl_days | Records for this record type will be deleted after this number of days. | | retention_column_name | The timestamp column used to determine record age for TTL expiry. One of `CREATED_AT` or `UPDATED_AT`. With `UPDATED_AT`, a record's age resets each time it's updated. | | on_limit_reached | Behavior when the record type reaches its per-type record limit. One of `REJECT` (block new writes) or `EVICT_OLDEST` (delete the oldest record to make room). | | max_records_limit | Custom per-record-type record limit, or `null` if no custom limit is set (in which case the tenant default applies). | | record_fields | An array of objects describing the custom record fields defined by the user. | | default_record_fields | An array of objects describing the default record fields (Timestamp and Story name). | ### Sample response ```json { "id": 1, "name": "Updated record type name", "description": "Updated description of the record type", "editable": true, "ttl_days": 7, "retention_column_name": "UPDATED_AT", "on_limit_reached": "EVICT_OLDEST", "max_records_limit": 5000, "team_id": 123, "record_fields": [ { "id": 1, "name": "Updated Column Name", "result_type": "TEXT_ENUM", "fixed_values": ["Option A", "Option B", "Option C"] }, { "id": 4, "name": "New Column", "result_type": "NUMBER", "fixed_values": [] } ], "default_record_fields": [ { "id": 2, "name": "Story name", "result_type": "TEXT", "fixed_values": [] }, { "id": 3, "name": "Timestamp", "result_type": "TIMESTAMP", "fixed_values": [] } ] } ``` #### List ## Description Retrieve a list of record types. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------- | | team_id | ID of team to which the record type belongs. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** The page number of results to fetch. | ```bash curl -X GET \ https:///api/v1/record_types?team_id=<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing record types in the specified team. ### Field description | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | The record type ID. | | name | The record type name. | | description | A short description of the record type, or null if not set. | | team_id | ID of team to which the record type belongs. | | editable | Whether the records for this record type are editable or not. | | ttl_days | Records for this record type will be deleted after this number of days. | | retention_column_name | The timestamp column used to determine record age for TTL expiry. One of `CREATED_AT` or `UPDATED_AT`. With `UPDATED_AT`, a record's age resets each time it's updated. | | on_limit_reached | Behavior when the record type reaches its per-type record limit. One of `REJECT` (block new writes) or `EVICT_OLDEST` (delete the oldest record to make room). | | max_records_limit | Custom per-record-type record limit, or `null` if no custom limit is set (in which case the tenant default applies). | | record_fields | An array of objects describing the custom record fields defined by the user. | | default_record_fields | An array of objects describing the default record fields (Timestamp and Story name). | ### Sample response ```json { "record_types": [ { "id": 1, "name": "Record type 1", "description": "Optional description of the record type", "team_id": 123, "editable": false, "ttl_days": 3, "retention_column_name": "UPDATED_AT", "on_limit_reached": "EVICT_OLDEST", "max_records_limit": 5000, "record_fields": [ { "id": 1, "name": "Field 1", "result_type": "TEXT", "fixed_values": [] } ], "default_record_fields": [ { "id": 2, "name": "Story name", "result_type": "TEXT", "fixed_values": [] }, { "id": 3, "name": "Timestamp", "result_type": "TIMESTAMP", "fixed_values": [] } ] }, { "id": 2, "name": "Record type 2", "description": null, "team_id": 123, "editable": false, "ttl_days": null, "retention_column_name": "CREATED_AT", "on_limit_reached": "REJECT", "max_records_limit": null, "record_fields": [ { "id": 4, "name": "Field 1", "result_type": "TEXT", "fixed_values": ["Value 1", "Value 2", "Value 3"] } ], "default_record_fields": [ { "id": 5, "name": "Story name", "result_type": "TEXT", "fixed_values": [] }, { "id": 6, "name": "Timestamp", "result_type": "TIMESTAMP", "fixed_values": [] } ] } ], "meta": { "current_page": "https:///api/v1/record_types?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 3 } } ``` #### Delete ## Description Delete a record type. Please be aware that this will also delete all associated records for this record type. ## Request HTTP Method: **DELETE** | Parameter | Description | | -------------- | ------------------------------------ | | record_type_id | The ID of the record type to delete. | ```bash curl -X DELETE \ https:///api/v1/record_types/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Record Views #### List ## Description A "record view" is a saved view within a record type that includes specified filters, charts, and table layout settings. Retrieve a paginated list of record views. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | **Optional** Only return record views belonging to this team. | | record_type_id | **Optional** Only return record views for this record type. | | order | **Optional** Order the results by one of: `NAME`, `RECENTLY_CREATED`, `RECENTLY_UPDATED`. Defaults to `NAME` when not specified or invalid. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 500. | | page | **Optional** The page number of results to fetch. Defaults to page 1. | ```bash curl -X GET \ "https:///api/v1/record_views?team_id=1&record_type_id=3&order=RECENTLY_UPDATED" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the record views the requesting token has access to. ### Field description | Parameter | Description | | ---------------- | ------------------------------------------------------------------------------- | | record_views | Array of objects each representing a record view. | | id | Integer ID of the record view. | | name | Name of the record view. | | team | Object describing the team this record view belongs to. | | team.id | Integer ID of the team. | | team.name | Name of the team. | | record_type | Object describing the record type used by this record view. | | record_type.id | Integer ID of the record type. | | record_type.name | Name of the record type. | | created_at | ISO 8601 timestamp representing when the record view was created. | | updated_at | ISO 8601 timestamp representing when the record view was last updated. | | report_view | The default view for the record view: `record_table`, `split_view`, or `chart`. | ### Sample response ```json { "record_views": [ { "id": 1, "name": "Open cases by priority", "team": { "id": 14, "name": "Security Operations" }, "record_type": { "id": 3, "name": "Cases" }, "created_at": "2025-02-10T12:30:45Z", "updated_at": "2025-02-12T09:15:22Z", "report_view": "record_table" }, { "id": 2, "name": "Incidents by source", "team": { "id": 14, "name": "Security Operations" }, "record_type": { "id": 3, "name": "Cases" }, "created_at": "2025-02-11T08:05:10Z", "updated_at": "2025-02-13T16:42:01Z", "report_view": "chart" } ], "meta": { "current_page": "https:///api/v1/record_views?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` #### Delete ## Description Delete a record view. ## Request HTTP Method: **DELETE** | Parameter | Description | | -------------- | ------------------------------------ | | record_view_id | The ID of the record view to delete. | ```bash curl -X DELETE \ https:///api/v1/record_views/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Export ## Description Export a record view. The response can be passed to the import endpoint to recreate the record view in another team or tenant. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ------------------------------------ | | record_view_id | The ID of the record view to export. | ```bash curl -X GET \ https:///api/v1/record_views/<>/export \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the record view in exported form. ### Field description | Parameter | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------- | | schema_version | The version of the export schema format. | | export_type | The type of the export, "record_view". | | exported_at | ISO 8601 timestamp representing when the export was generated. | | record_view | Object containing the record view configuration. Pass this object to the import endpoint to recreate the record view. | ### Sample response ```json { "schema_version": 1, "export_type": "record_view", "exported_at": "2025-02-10T12:30:45Z", "record_view": { "name": "Open cases by priority", "report_view": "chart", "elements": [ { "id": "a1b2c3d4e5f6", "name": "Priority breakdown", "record_type_name": "Cases", "element_type": "chart", "axes": [ { "direction": "x", "record_field_name": "priority" } ], "aggregation": "count", "rolling_date_range": null, "range_start": null, "range_end": null, "filters": { "stories": [], "fields": [ { "value": "open", "operator": "equals", "name": "status" } ] }, "order": { "field": null, "direction": null }, "color_palette": "default", "options": {}, "record_fields": [], "test_mode": false } ], "layout": [ { "i": "a1b2c3d4e5f6", "x": 0, "y": 0, "w": 6, "h": 4 } ] } } ``` #### Import ## Description Import a record view. The import data should be obtained from the [export endpoint](/api/record_views/export). ## Request HTTP Method: **POST** | Body Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | ID of the team to which the record view should be added. | | data | JSON object representing the record view in [exported form](/api/record_views/export#sample-response). | | mode | **Optional** Create a new record view or replace an existing one by name (`new`, `replace`). Defaults to `new`. | | name | **Optional** Name for the record view. Defaults to the name in the export data. In `replace` mode, this specifies which existing view to replace. | ```bash curl -X POST \ https:///api/v1/record_views/import \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "team_id": 14, "name": "Imported view", "mode": "new", "data": { "schema_version": 1, "record_view": { "name": "Open cases by priority", "report_view": "chart", "elements": [], "layout": [] } } }' ``` ## Response A successful request will return a JSON object describing the newly created record view with a `201` status code. ### Field description | Parameter | Description | | ---------- | ---------------------------------------------------------------------- | | id | Integer ID of the record view. | | name | Name of the record view. | | team | Object describing the team this record view belongs to. | | team.id | Integer ID of the team. | | team.name | Name of the team. | | created_at | ISO 8601 timestamp representing when the record view was created. | | updated_at | ISO 8601 timestamp representing when the record view was last updated. | ### Sample response ```json { "id": 42, "name": "Imported view", "team": { "id": 14, "name": "Security Operations" }, "created_at": "2025-02-14T10:30:00Z", "updated_at": "2025-02-14T10:30:00Z" } ``` ## Reporting ### Time saved ## Description Returns timed and dated records of time saved by using Tines. See [Reporting](https://www.tines.com/docs/actions/reporting/) for more information. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ----------------------------------------------------------------------------------------- | | start_date | **Optional** ISO 8601 timestamp to only include records from after this datetime. | | end_date | **Optional** ISO 8601 timestamp to only include records from before this datetime. | | date_unit | **Optional** Arrange the data by hour, day, week, or month. Default: day | | fill_gaps | **Optional** If true, fill any empty rows with explicit 0 time saved. Default: true | | team_id | **Optional** Only show time saved data for the selected team | | story_id | **Optional** Only show time saved data for the selected story | | action_id | **Optional** Only show time saved data for the selected action | | per_page | **Optional** Set the number of records returned per page. Defaults to 20, maximum is 500. | | page | **Optional** The page number of results to fetch. | ```bash curl -X GET \ https:///api/v1/reporting/time_saved \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful response will return a list of time saved data according to the query parameters. ### Field description | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | date | ISO8601-compliant UTC timestamp of the date/time that time was saved in (rounded down to the nearest hour, day, week, month depending on the setting of date_unit) | | value | Time saved in seconds | ### Sample response ```json { "time_saved": [ { "date": "2022-08-11T00:00:00Z", "value": 1980 }, { "date": "2022-08-12T00:00:00Z", "value": 0 }, { "date": "2022-08-13T00:00:00Z", "value": 0 }, { "date": "2022-08-14T00:00:00Z", "value": 0 }, { "date": "2022-08-15T00:00:00Z", "value": 4500 }, { "date": "2022-08-16T00:00:00Z", "value": 0 }, { "date": "2022-08-17T00:00:00Z", "value": 900 }, { "date": "2022-08-18T00:00:00Z", "value": 0 }, { "date": "2022-08-19T00:00:00Z", "value": 0 }, { "date": "2022-08-20T00:00:00Z", "value": 0 }, { "date": "2022-08-21T00:00:00Z", "value": 0 }, { "date": "2022-08-22T00:00:00Z", "value": 0 }, { "date": "2022-08-23T00:00:00Z", "value": 600 }, { "date": "2022-08-24T00:00:00Z", "value": 0 } ], "meta": { "current_page": "http:///api/v1/reporting/time_saved?team_id=14&per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 14 } } ``` ## Admin ### Action egress control rules #### Create ## Description Create a new Action egress control rule. ## Request HTTP Method: **POST** ### Field description | Field | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ip | IP address or CIDR range of the rule. | | fqdn | The fqdn for the rule. Only IP or FQDN is allowed, not both. | | description | Human-readable description of the rule. | | allowed_action_types | Array of action types allowed to use the IP or FQDN. The options are "http-request" and "send-email". Any other strings will not work. **Note:** Send email allowlist is available for FQDNs only. | ### Sample request ```bash curl -X POST \ https:///api/v1/admin/action_egress_control_rules \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "ip": "192.168.1.1", "description": "Example IP", "allowed_action_types": ["http-request"] }' ``` ```bash curl -X POST \ https:///api/v1/admin/action_egress_control_rules \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "fqdn": "sub.example.com", "description": "Example FQDN", "allowed_action_types": ["http-request", "send-email"] }' ``` ## Response A successful request will return status 201 and the created Action egress control rule object. See `list` for more details about the rule object. #### Get ## Description Get an Action egress control rule by ID. ## Request HTTP Method: **GET** ### Field description | Field | Description | | ----- | ------------------------------ | | id | Action egress control rule ID. | ### Sample request ```bash curl -X GET \ https:///api/v1/admin/action_egress_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an object with an Action egress control rule. ### Sample response ```json { "id": 1, "ip": "192.168.1.1", "fqdn": null, "description": "Example IP", "allowed_action_types": ["http-request"], "created_at": "2024-07-25T16:44:01Z", "updated_at": "2024-07-25T16:44:11Z" } ``` #### Update ## Description Update an existing action egress control rule. ## Request HTTP Method: **PUT**, **PATCH** ### Field description | Field | Description | | ----------- | --------------------------------------- | | id | IP access control rule ID. | | ip | IP address or CIDR range of the rule. | | description | Human-readable description of the rule. | ### Sample requests ```bash curl -X PUT \ https:///api/v1/admin/ip_access_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "ip": "192.168.1.1", "description": "Example IP" }' ``` ```bash curl -X PUT \ https:///api/v1/admin/ip_access_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "fqdn": "tines.io", "description": "Example FQDN", "allowed_action_types": ["http-request", "send-email"] }' ``` ## Response A successful request will return status 200 and the updated IP access control rule object. See `list` for more details about the rule object. #### List ## Description List Action egress control rules for the tenant. Please note that these only take effect if [Action egress control](https://www.tines.com/docs/admin/action-egress-control/) is enabled. ## Request HTTP Method: **GET** ### Field description | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ### Sample request ```bash curl -X GET \ https:///api/v1/admin/action_egress_control_rules \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an an object with a list of Action egress control rules. ### Field description | Parameter | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | id | Action egress control rule ID. | | ip | IP address or CIDR range of the rule. | | description | Human-readable description of the rule. | | allowed_action_types | List of action types the IP or FQDN is allowed for. This list will include "send-email", "http-request", or both. | | created_at | Timestamp describing when the rule was created. | | updated_at | Timestamp describing when the rule was last updated. | ### Sample response ```json { "admin/action_egress_control_rules": [ { "id": 1, "ip": "192.168.1.1", "fqdn": null, "description": "Example IP", "allowed_action_types": ["http-request"], "created_at": "2024-07-25T16:29:48Z", "updated_at": "2024-07-25T16:29:48Z" } ], "meta": { "current_page": "https:///api/v1/admin/action_egress_control_rules?&per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete ## Description Delete an existing Action egress control rule. ## Request HTTP Method: **DELETE** ### Field description | Field | Description | | ----- | ------------------------------ | | id | Action egress control rule ID. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/admin/action_egress_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a 204 (no content) response. ### Custom certificate authority #### Set ## Description Set a custom certificate authority for use by all of your IMAP and HTTP Request actions. ## Request HTTP Method: **PUT** | Parameter | Description | | ----------- | ----------------------------------------------------------------------------------------- | | certificate | PEM encoded X.509 public certificate (or certificate chain) of your certificate authority | | name | **Optional** Name of your customer certificate authority. Default value: `default` | ### Sample request ```bash curl -X PUT \ https:///api/v1/admin/custom_certificate_authority \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "certificate": "", }' ``` ## Response A successful request will return an empty response with a `200` status code. A failed request will return a `422` status code. ### IP Access Control #### Create ## Description Create a new IP access control rule. ## Request HTTP Method: **POST** ### Field description | Field | Description | | ----------- | --------------------------------------- | | ip | IP address or CIDR range of the rule. | | description | Human-readable description of the rule. | ### Sample request ```bash curl -X POST \ https:///api/v1/admin/ip_access_control_rules \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "ip": "192.168.1.1", "description": "Example IP" }' ``` ## Response A successful request will return status 201 and the created IP access control rule object. See `list` for more details about the rule object. #### Get ## Description Get an IP access control rule by ID. ## Request HTTP Method: **GET** ### Field description | Field | Description | | ----- | -------------------------- | | id | IP access control rule ID. | ### Sample request ```bash curl -X GET \ https:///api/v1/admin/ip_access_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an object with an IP access control rule. ### Sample response ```json { "id": 1, "ip": "192.168.1.1", "description": "Example IP", "created_at": "2024-07-25T16:44:01Z", "updated_at": "2024-07-25T16:44:11Z" } ``` #### Update ## Description Update an existing IP access control rule. ## Request HTTP Method: **PUT**, **PATCH** ### Field description | Field | Description | | ----------- | --------------------------------------- | | id | IP access control rule ID. | | ip | IP address or CIDR range of the rule. | | description | Human-readable description of the rule. | ### Sample request ```bash curl -X PUT \ https:///api/v1/admin/ip_access_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "ip": "192.168.1.1", "description": "Example IP" }' ``` ## Response A successful request will return status 200 and the updated IP access control rule object. See `list` for more details about the rule object. #### List ## Description List IP access control rules for the tenant. Please note that these only take effect if [IP access control](https://www.tines.com/docs/admin/ip-access-control/) is enabled. ## Request HTTP Method: **GET** ### Field description | Parameter | Description | | ----------- | --------------------------------------------------------------------------------------------------- | | matching_ip | **Optional** An address or CIDR to filter rules and return only matching ones. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ### Sample request ```bash curl -X GET \ https:///api/v1/admin/ip_access_control_rules?matching_ip=192.168.1.1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an an object with a list of IP access control rules. ### Field description | Parameter | Description | | ----------- | ---------------------------------------------------- | | id | IP access control rule ID. | | ip | IP address or CIDR range of the rule. | | description | Human-readable description of the rule. | | created_at | Timestamp describing when the rule was created. | | updated_at | Timestamp describing when the rule was last updated. | ### Sample response ```json { "admin/ip_access_control_rules": [ { "id": 1, "ip": "192.168.1.1", "description": "Example IP", "created_at": "2024-07-25T16:29:48Z", "updated_at": "2024-07-25T16:29:48Z" } ], "meta": { "current_page": "https:///api/v1/admin/ip_access_control_rules?matching_ip=192.168.1.1&per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete ## Description Delete an existing IP access control rule. ## Request HTTP Method: **DELETE** ### Field description | Field | Description | | ----- | -------------------------- | | id | IP access control rule ID. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/admin/ip_access_control_rules/1 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a 204 (no content) response. ### Jobs #### List dead ## Description Retrieve a list of dead jobs from the Tines tenant. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------- | | page | **Optional** Retrieve page number from the paginated list. Defaults to 1. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | ```bash curl -X GET \ https:///api/v1/admin/dead_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing dead jobs in the Tines tenant. ### Field description | Parameter | Description | | --------------- | ---------------------------------------------------------------- | | id | Job ID. | | type | Job type. | | agent (Hash) | Contains action description (AgentReceiveJob type entries only). | | agent (Integer) | Action ID (CredentialRefreshJob type entries only). | | events | Event ID. | | retry_count | Amount of times the job has been retried. | | last_retry | Time of the last retry. | | error_class | Job error type. | ### Sample response ```json { "admin/dead_jobs": [ { id: 1234, type: "AgentReceiveJob", agent: { id: 1, name: "Action 01", }, events: 1, retry_count: 5, last_retry: 1567399360.056226, error_class: ArgumentError }, { id: 1237, type: "CredentialRefreshJob", agent: 1, retry_count: 5, last_retry: "", error_class: ArgumentError } ] "meta": { "current_page": "https:///api/v1/admin/dead_jobs?page=1&per_page=20", "previous_page": null, "next_page": "https:///api/v1/admin/dead_jobs?page=2&per_page=20", "next_page_number": 2, "per_page": 20, "pages": 0, "count": 0 } } ``` #### List in-progress ## Description Retrieve a list of in progress jobs from the Tines tenant. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------- | | page | **Optional** Retrieve page number from the paginated list. Defaults to 1. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | ```bash curl -X GET \ https:///api/v1/admin/in_progress_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing in progress jobs in the Tines tenant. ### Field description | Parameter | Description | | ------------ | ---------------------------------------------------------------- | | id | Job ID. | | type | Job type. | | agent (Hash) | Contains action description (AgentReceiveJob type entries only). | | events | Event ID. | | started_at | Job starting time. | ### Sample response ```json { "admin/in_progress_jobs": [ { "id": 1234, "type": "AgentReceiveJob", "agent": { "id": 1, "name": "Action 01" }, "events": 1, "started_at": 1567399360.056226 } ], "meta": { "current_page": "https:///api/v1/admin/in_progress_jobs?page=1&per_page=20", "previous_page": null, "next_page": "https:///api/v1/admin/in_progress_jobs?page=2&per_page=20", "next_page_number": 2, "per_page": 20, "pages": 0, "count": 0 } } ``` #### List queued jobs ## Description Fetch the current queue of jobs from the Tines tenant. This API endpoint is specifically for dedicated tenants. It provides a snapshot of the job queue as it exists at the moment the request is sent. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------- | | page | **Optional** Retrieve page number from the paginated list. Defaults to 1. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | ```bash curl -X GET \ https:///api/v1/admin/queued_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing queued jobs in the Tines tenant. ### Field description | Parameter | Description | | ------------ | ---------------------------------------------------------------- | | id | Job ID. | | type | Job type. | | agent (Hash) | Contains action description (AgentReceiveJob type entries only). | | events | Event ID. | | started_at | Job starting time. | ### Sample response ```json { "admin/queued_jobs": [ { "id": 1234, "type": "AgentReceiveJob", "agent": { "id": 1, "name": "Agent 01" }, "events": 1, "retry_count": 5, "last_retry": 1567399360.056226, "error_class": "ArgumentError" }, { "id": 1237, "type": "CredentialRefreshJob", "agent": 1, "retry_count": 5, "last_retry": "", "error_class": "ArgumentError" } ], "meta": { "current_page": "https:///api/v1/admin/queued_jobs?page=1&per_page=20", "previous_page": null, "next_page": "https:///api/v1/admin/queued_jobs?page=2&per_page=20", "next_page_number": 2, "per_page": 20, "pages": 0, "count": 0 } } ``` #### List retry jobs ## Description Retrieve a list of retry jobs from the Tines tenant. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------- | | page | **Optional** Retrieve page number from the paginated list. Defaults to 1. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | ```bash curl -X GET \ https:///api/v1/admin/retry_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing retry jobs in the Tines tenant. ### Field description | Parameter | Description | | --------------- | ---------------------------------------------------------------- | | id | Job ID. | | type | Job type. | | agent (Hash) | Contains action description (AgentReceiveJob type entries only). | | agent (Integer) | Action ID (CredentialRefreshJob type entries only). | | events | Event ID. | | retry_count | Amount of times the job has been retried. | | last_retry | Time of the last retry. | | error_class | Job error type. | ### Sample response ```json { "admin/retry_jobs": [ { "id": 1234, "type": "AgentReceiveJob", "agent": { "id": 1, "name": "Action 01" }, "events": 1, "retry_count": 5, "last_retry": 1567399360.056226, "error_class": "ArgumentError" }, { "id": 1237, "type": "CredentialRefreshJob", "agent": 1, "retry_count": 5, "last_retry": "", "error_class": "ArgumentError" } ], "meta": { "current_page": "https:///api/v1/admin/retry_jobs?page=1&per_page=20", "previous_page": null, "next_page": "https:///api/v1/admin/retry_jobs?page=2&per_page=20", "next_page_number": 2, "per_page": 20, "pages": 0, "count": 0 } } ``` #### Delete all dead ## Description Delete all dead jobs from the Tines tenant. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **DELETE** ```bash curl -X DELETE \ https:///api/v1/admin/delete_all_dead_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete all queued ## Description Delete all queued jobs from the Tines tenant. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **DELETE** ```bash curl -X DELETE \ https:///api/v1/admin/delete_all_queued_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Delete all retry ## Description Delete all retry jobs from the Tines tenant. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **DELETE** ```bash curl -X DELETE \ https:///api/v1/admin/delete_all_retry_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### By Action ##### Delete dead ## Description Delete all dead jobs by action id. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ----------------- | | action-id | ID of the action. | ```bash curl -X DELETE \ https:///api/v1/admin/actions/<>/delete_all_dead_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ##### Delete queued ## Description Delete all queued jobs by action id. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ----------------- | | action-id | ID of the action. | ```bash curl -X DELETE \ https:///api/v1/admin/actions/<>/delete_all_queued_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ##### Delete retry ## Description Delete all retry jobs by action id. This endpoint is relevant for dedicated tenants only. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ----------------- | | action-id | ID of the action. | ```bash curl -X DELETE \ https:///api/v1/admin/actions/<>/delete_all_retry_jobs \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Roles #### Create ## Description Create a custom role in a Tines tenant. ## Request HTTP Method: **POST** | Body Parameter | Description | | -------------- | -------------------------------------------------------- | | name | **Required** Role name. | | description | **Optional** A description of the role. | | permissions | **Required** A list of permissions to apply to the role. | ### Sample request ```bash curl -X POST \ https:///api/v1/admin/roles \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "MY_ROLE", "description": "My fantastic role", "permissions": ["STORY_CREATE"] }' ``` ## Response A successful request will return a JSON object describing the created role. ### Field description | Parameter | Description | | ----------- | -------------------------------------------------------------------------------- | | id | Role ID. | | name | Role name. | | type | Role type - custom. | | description | Role description. | | permissions | Array of applied permissions. | | created_at | Timestamp describing when the role was created. | | updated_at | Timestamp describing when the role was last updated. | | builder | Boolean indicating whether this role grants builder / story editing permissions. | ### Sample response ```json { "id": "123", "name": "MY_ROLE", "type": "custom", "description": "My fantastic role", "permissions": ["STORY_CREATE"], "created_at": "2019-11-03T09:57:49.537Z", "updated_at": "2019-11-03T09:57:49.537Z", "builder": true } ``` #### Get ## Description Retrieve details of a specific (default or custom type) role. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ----------------------- | | role_id | ID or name of the role. | ```bash curl -X GET \ https:///api/v1/admin/roles/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the role. ### Field description | Parameter | Description | | ----------- | -------------------------------------------------------------------------------- | | id | Role ID. | | name | Role name. | | type | Role type - custom or default. | | description | Role description. | | permissions | Array of applied permissions. | | created_at | Timestamp describing when the role was created. | | updated_at | Timestamp describing when the role was last updated. | | builder | Boolean indicating whether this role grants builder / story editing permissions. | ### Sample response ```json { "id": "123", "name": "MY_ROLE", "type": "custom", "description": "My fantastic role", "permissions": ["STORY_CREATE"], "created_at": "2019-11-03T09:57:49.537Z", "updated_at": "2019-11-03T09:57:49.537Z", "builder": true } ``` #### Update ## Description Update a Role. ## Request HTTP Method: **PATCH** | Body Parameter | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | description | **Optional** Role description. | | permissions | **Optional** Array of permission names, from the [list of available permissions](https://www.tines.com/docs/admin/teams/#permissions-table). | | Path Parameter | Description | | -------------- | ----------------------- | | role_id | ID or name of the role. | ### Sample request ```bash curl -X PATCH \ https:///api/v1/admin/roles/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "permissions": ["CASE_CREATE"] }' ``` ## Response A successful request will return a JSON object describing the updated role. ### Field description | Parameter | Description | | ----------- | -------------------------------------------------------------------------------- | | id | Role ID. | | name | Role name. | | type | Role type - custom. | | description | Role description. | | permissions | Array of applied permissions. | | created_at | Timestamp describing when the role was created. | | updated_at | Timestamp describing when the role was last updated. | | builder | Boolean indicating whether this role grants builder / story editing permissions. | ### Sample response ```json { "id": "123", "name": "MY_ROLE", "type": "custom", "description": "My fantastic role", "permissions": ["CASE_CREATE"], "created_at": "2019-11-03T09:57:49.537Z", "updated_at": "2019-11-03T09:57:49.537Z", "builder": false } ``` #### List ## Description Retrieve a list of roles (both default and custom) from the Tines tenant. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/admin/roles \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array of roles in the Tines tenant. ### Field description | Parameter | Description | | ----------- | -------------------------------------------------------------------------------- | | id | Role ID. | | name | Role name. | | type | Role type - custom or default. | | description | Role description. | | permissions | Array of applied permissions. | | created_at | Timestamp describing when the role was created. | | updated_at | Timestamp describing when the role was last updated. | | builder | Boolean indicating whether this role grants builder / story editing permissions. | ### Sample response ```json { "admin/roles": [ { "id": "TEAM_ADMIN", "name": "TEAM_ADMIN", "type": "default", "description": "Manage members, stories, credentials, resources and change control.", "permissions": ["ALLOW_ALL"], "created_at": null, "updated_at": null, "builder": true }, { "id": "123", "name": "MY_ROLE", "type": "custom", "description": "My fantastic role", "permissions": ["STORY_CREATE"], "created_at": "2019-11-03T09:57:49.537Z", "updated_at": "2019-11-03T09:57:49.537Z", "builder": true } ], "meta": { "current_page": "https:///api/v1/admin/roles?page=1&per_page=20", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` #### Delete ## Description Delete a specific custom role. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ----------------------- | | role_id | ID or name of the role. | ```bash curl -X DELETE \ https:///api/v1/admin/roles/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### SCIM user group mapping #### Get ## Description Get the SCIM user group mapping for the tenant. ## Request HTTP Method: **GET** ### Sample request ```bash curl -X GET \ https:///api/v1/admin/scim_user_group_mapping \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an object with the SCIM user group mapping. ### Sample response ```json { "mappings": [ { "group_name": "Managers", "team_name": "Analytics", "role_name": "TEAM_ADMIN" }, { "group_name": "Managers", "team_name": "Incident Response", "role_name": "EDITOR" }, { "group_name": "Analysts", "team_name": "Analytics", "role_name": "EDITOR" }, { "group_name": "Everyone", "team_name": "Incident Response", "role_name": "VIEWER" } ] } ``` #### Update ## 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. ## Request HTTP Method: **POST** ### Sample request ```bash curl -X POST \ https:///api/v1/admin/scim_user_group_mapping \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "user_group_mapping": { "mappings": [ { "group_name": "Managers", "team_name": "Analytics", "role_name": "TEAM_ADMIN" } ], "tenant_owners_group": "Managers" } }' ``` ## Response A successful request will return status 200 and the updated SCIM user group mapping. ### Self Hosted License #### Create ## Description Upload and apply a new license to the tenant. A license must not already exist — use [Update](/api/admin/self-hosted-license/update/) to replace an existing license. This endpoint is only available on self-hosted tenants. ## Request HTTP Method: **POST** | Parameter | Description | | --------- | -------------------------- | | license | The signed license string. | ### Sample request ```bash curl -X POST \ https:///api/v1/admin/license \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "license": "TINES-company_name-ENV::LICENSE_DATA" }' ``` ## Response A successful request will return a `201` status code with a JSON object describing the applied license. The response fields are the same as [Get](/api/admin/self-hosted-license/get/). ### Sample response ```json { "customer_name": "Company Name", "unique_identifier": "UUID", "environment": "Production", "created_at": "2026-01-01T00:00:00.000Z", "expires_at": "2027-01-01T00:00:00Z", "pricing_model": "story_units", "users": 1000, "builders": 100, "teams": 5, "stories": 100, "story_units": 50, "actions": 1000000, "tunnels": 0, "daily_story_events": 50000, "daily_tenant_events": 100000, "features": ["AUDIT_LOGS", "CHANGE_CONTROL", "SSO"] } ``` A request when a license already exists will return a `409` status code. A request with an invalid license will return a `422` status code. #### Get ## Description Retrieve the current license details for the tenant. This endpoint is only available on self-hosted tenants. ## Request HTTP Method: **GET** ### Sample request ```bash curl -X GET \ https:///api/v1/admin/license \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the current license. ### Field description | Parameter | Description | | ------------------- | -------------------------------------------------- | | customer_name | The customer name on the license. | | unique_identifier | The unique identifier for the license. | | environment | The environment the license is issued for. | | created_at | Timestamp describing when the license was created. | | expires_at | Timestamp describing when the license expires. | | pricing_model | The pricing model for the tenant. | | users | Maximum number of users allowed. | | builders | Maximum number of builders allowed. | | teams | Maximum number of teams allowed. | | stories | Maximum number of stories allowed. | | story_units | Maximum number of story units allowed. | | actions | Maximum number of actions allowed. | | tunnels | Maximum number of tunnels allowed. | | daily_story_events | Maximum number of daily story events allowed. | | daily_tenant_events | Maximum number of daily tenant events allowed. | | features | Array of feature names enabled by the license. | ### Sample response ```json { "customer_name": "Company Name", "unique_identifier": "UUID", "environment": "Production", "created_at": "2026-01-01T00:00:00.000Z", "expires_at": "2027-01-01T00:00:00Z", "pricing_model": "story_units", "users": 1000, "builders": 100, "teams": 5, "stories": 100, "story_units": 50, "actions": 1000000, "tunnels": 0, "daily_story_events": 50000, "daily_tenant_events": 100000, "features": ["AUDIT_LOGS", "CHANGE_CONTROL", "SSO"] } ``` A request to a tenant with no license will return a `404` status code. #### Update ## Description Update and apply a new license to the tenant, replacing the existing one. A license must already exist — use [Create](/api/admin/self-hosted-license/create/) to apply the first license. This endpoint is only available on self-hosted tenants. ## Request HTTP Method: **PUT** | Parameter | Description | | --------- | -------------------------- | | license | The signed license string. | ### Sample request ```bash curl -X PUT \ https:///api/v1/admin/license \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "license": "TINES-company_name-ENV::LICENSE_DATA" }' ``` ## Response A successful request will return a `200` status code with a JSON object describing the updated license. The response fields are the same as [Get](/api/admin/self-hosted-license/get/). ### Sample response ```json { "customer_name": "Company Name", "unique_identifier": "UUID", "environment": "Production", "created_at": "2026-01-01T00:00:00.000Z", "expires_at": "2027-01-01T00:00:00Z", "pricing_model": "story_units", "users": 1000, "builders": 100, "teams": 5, "stories": 100, "story_units": 50, "actions": 1000000, "tunnels": 0, "daily_story_events": 50000, "daily_tenant_events": 100000, "features": ["AUDIT_LOGS", "CHANGE_CONTROL", "SSO"] } ``` A request when no license exists will return a `404` status code. A request with an invalid license will return a `422` status code. ### Story sync destinations #### Create ## Description Create a new sync destination and subscribe it to one or more stories. ## Request HTTP Method: **POST** | Body parameter | Description | | -------------------------- | -------------------------------------------------------------------------- | | destination_tenant_url | Base URL of the destination tenant. | | destination_tenant_api_key | Tines API key used to publish to the destination tenant. | | destination_team_id | ID of the team on the destination tenant that will own the synced stories. | | team_id | ID of the team on the current tenant creating the sync. | | story_ids | Array of story IDs (from the current tenant) to sync. | ```bash curl -X POST \ https:///api/v1/admin/sync_destinations \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "destination_tenant_url": "https://", "destination_tenant_api_key": "<>", "destination_team_id": 42, "team_id": 7, "story_ids": [9981, 9982] }' ``` ## Response Returns the newly‑created sync destination object, with a `201 Created` status. ### Field description | Parameter | Description | | ----------------------------- | ---------------------------------------------------------------------------- | | id | Sync destination ID. | | destination_tenant_url | Base URL of the destination tenant (e.g. https://). | | destination_team_id | ID of the destination team receiving the synced stories. | | origin_team_id | ID of the team on the current tenant where the sync destination was created. | | subscriptions | Array of subscription objects (one per story). | | subscriptions[].story.id | ID of the story. | | subscriptions[].story.name | Name of the story. | | subscriptions[].status | Sync status. One of `synced`, `failed`, or `requires_sync`. | | subscriptions[].error_message | Error details if `status` is `failed`; `null` otherwise. | | | ### Sample response ```json { "sync_destination": { "id": 24, "destination_tenant_url": "https://", "destination_team_id": 42, "origin_team_id": 7, "subscriptions": [ { "story": { "id": 9981, "name": "High‑Priority Alerts" }, "status": "synced", "error_message": null }, { "story": { "id": 9982, "name": "Change Control Requests" }, "status": "synced", "error_message": null } ] } } ``` #### List ## Description Retrieve a paginated list of sync destinations configured on the tenant. ## Request HTTP Method: **GET** | Query parameter | Description | | --------------- | ---------------------------------------- | | per_page | **Optional** Number of results per page. | | page | **Optional** Page of results to return. | ```bash curl -X GET \ https:///api/v1/admin/sync_destinations \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request returns a JSON Array of sync destination objects. ### Field description | Parameter | Description | | ----------------------------- | ---------------------------------------------------------------------------- | | id | Sync destination ID. | | destination_tenant_url | Base URL of the destination tenant (e.g. https://). | | destination_team_id | ID of the destination team receiving the synced stories. | | origin_team_id | ID of the team on the current tenant where the sync destination was created. | | subscriptions | Array of subscription objects (one per story). | | subscriptions[].story.id | ID of the story. | | subscriptions[].story.name | Name of the story. | | subscriptions[].status | Sync status. One of `synced`, `failed`, or `requires_sync`. | | subscriptions[].error_message | Error details if `status` is `failed`; `null` otherwise. | ### Sample response ```json { "sync_destinations": [ { "id": 23, "destination_tenant_url": "https://", "destination_team_id": 42, "origin_team_id": 7, "subscriptions": [ { "story": { "id": 9981, "name": "Example" }, "status": "synced", "error_message": null } ] } ], "meta": { "current_page": "https:///api/v1/admin/sync_destinations?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete ## Description Remove a sync destination configuration. ## Request HTTP Method: **DELETE** | URL parameter | Description | | ------------- | ------------------------------------- | | id | ID of the sync destination to delete. | ```bash curl -X DELETE \ https:///api/v1/admin/sync_destinations/24 \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response On success a `204 No Content` status is returned and the body is empty. #### Manual sync ## Description Trigger an immediate push of all subscribed stories to the destination tenant. ## Request HTTP Method: **POST** | URL Parameter | Description | | ------------- | -------------------------------------- | | id | ID of the sync destination to sync to. | ```bash curl -X POST \ https:///api/v1/admin/sync_destinations/24/manual_sync \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request returns a confirmation object, with a `200 OK` status. ### Sample response ```json { "sync_initiated": true } ``` ### Templates #### Create ## Description Create a private template. ## Request HTTP Method: **POST** | Query Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of template. | | description | Template description. | | vendor | Vendor name. | | product | Product name. | | agent_type | Type of action to create:
`Agents::EmailAgent`
`Agents::EventTransformationAgent`
`Agents::HTTPRequestAgent`
`Agents::IMAPAgent`
`Agents::LLMAgent`
`Agents::TriggerAgent`
`Agents::WebhookAgent`
`Agents::SendToStoryAgent`
| | agent_options | JSON object with action options. | | team_id | **Optional** ID of team to which the template belongs. | | folder_id | **Optional** ID of the folder to place the template in. The folder must be a template folder belonging to the same team as the template. | | read_access | **Optional** Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). Default: `TEAM` when `team_id` passed, `GLOBAL` otherwise. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this template can be used. Required to set `read_access` to `SPECIFIC_TEAMS`. Default: `[]` (empty array). | | action_inputs | **Optional** Array of input parameters for the template. See [action_inputs structure](#action-inputs-structure) below. | ```bash curl -X POST \ https:///api/v1/admin/templates \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "Test API Name", "description": "test", "agent_type": "Agents::EventTransformationAgent", "vendor": "API", "product": "API", "agent_options": { "mode": "extract", "matchers": [ { "path": "{{.text}}", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "{{.text}}", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message" }, "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "The text to extract from", "required": true } ] }' ``` ## Response A successful request will return the created private template. ### Field description | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | id | Template ID. | | name | Template name. | | description | Template description. | | agent_type | Type of action associated with the template. | | agent_options | Action options. | | vendor | Vendor name. | | product | Product name. | | team_id | ID of team to which the template belongs. | | folder_id | ID of the folder containing the template, or `null` if the template is not in a folder. | | read_access | Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this template can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | action_inputs | **Optional** Array of input parameters for the template. See details below. | ### action_inputs structure Each object in the `action_inputs` array can have the following fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------- | | name | **Required** Input parameter name. | | type | **Required** Input type. One of: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `OBJECT`, `OPTION`, `CODE`, `CREDENTIAL`. | | required | Whether the input is required. Defaults to `false`. Must be `true` for `CREDENTIAL` type. | | description | **Optional** Description of the input parameter. | | default_value | **Optional** Default value for the input. | | data | **Optional** Type-specific configuration object. See below. | The `data` object varies by type: _Note: The `data` field is only applicable to `OBJECT`, `OPTION` and `CODE` types. Other types do not use this field._ | Type | data fields | | ------ | ------------------------------------------------------------------------- | | OBJECT | `json_schema`: JSON schema for validation. | | OPTION | `options`: Array of option values. `multi_select_enabled`: Boolean. | | CODE | `code_language`: Language for syntax highlighting (e.g., `HTML`, `JSON`). | #### Type-specific default_value types | Type | Expected default_value type | | ---------- | ------------------------------------- | | TEXT | String | | NUMBER | Integer (or formula string) | | BOOLEAN | Boolean (or formula string) | | DATE | String | | OBJECT | Any valid JSON value | | OPTION | Array (or formula string) | | CODE | String | | CREDENTIAL | Not supported (field must be omitted) | _Formula strings start with `=` (e.g., `=INPUT.name`) or `\\=` for escaped formulas._ #### CREDENTIAL type restrictions `CREDENTIAL` inputs only accept `name`, `type`, and `required` fields. The `description`, `default_value`, and `data` fields are not permitted and will cause a validation error if included. ### Validation constraints The following constraints are enforced when creating a template with `action_inputs`: - **Maximum of 300** action inputs per template. - **Only one** `CREDENTIAL` input is allowed per template. - Input **names must be unique** across all action inputs. - `CREDENTIAL` inputs must have `required` set to `true`. ### Sample response ```json { "id": 472463921472463921, "name": "Test API Name", "description": "test", "agent_type": "Agents::EventTransformationAgent", "agent_options": { "mode": "extract", "matchers": [ { "path": "", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message" }, "vendor": "API", "product": "API", "team_id": 1, "folder_id": 42, "read_access": "TEAM", "shared_team_slugs": [], "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "The text to extract from", "required": true } ] } ``` #### Get ## Description Retrieve a private template ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ---------------- | | template_id | The template id. | ```bash curl -X GET \ https:///api/v1/admin/templates/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a private template. ### Field description | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | id | Template ID. | | name | Template name. | | description | Template description. | | agent_type | Type of action associated with the template. | | agent_options | Action options. | | vendor | Vendor name. | | product | Product name. | | team_id | ID of team to which the template belongs. | | folder_id | ID of the folder containing the template, or `null` if the template is not in a folder. | | read_access | Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this template can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | action_inputs | **Optional** Array of input parameters for the template. See details below. | ### action_inputs structure Each object in the `action_inputs` array can have the following fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------- | | name | **Required** Input parameter name. | | type | **Required** Input type. One of: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `OBJECT`, `OPTION`, `CODE`, `CREDENTIAL`. | | required | Whether the input is required. Defaults to `false`. Must be `true` for `CREDENTIAL` type. | | description | **Optional** Description of the input parameter. | | default_value | **Optional** Default value for the input. | | data | **Optional** Type-specific configuration object. See below. | The `data` object varies by type: _Note: The `data` field is only applicable to `OBJECT`, `OPTION` and `CODE` types. Other types do not use this field._ | Type | data fields | | ------ | ------------------------------------------------------------------------- | | OBJECT | `json_schema`: JSON schema for validation. | | OPTION | `options`: Array of option values. `multi_select_enabled`: Boolean. | | CODE | `code_language`: Language for syntax highlighting (e.g., `HTML`, `JSON`). | ### Sample response ```json { "id": "472463921472463921", "name": "Extract some text", "description": "test", "agent_type": "Agents::EventTransformationAgent", "agent_options": { "mode": "extract", "matchers": [ { "path": "", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message" }, "vendor": "API", "product": "API", "team_id": 1, "folder_id": 42, "read_access": "TEAM", "shared_team_slugs": [], "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "The text to extract from", "required": true, "default_value": "Sample text" } ] } ``` #### Update ## Description Update a private template. ## Request HTTP Method: **PUT** | Query Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | Name of template. | | description | Template description. | | vendor | Vendor name. | | product | Product name. | | agent_type | Type of action to create:
`Agents::EmailAgent`
`Agents::EventTransformationAgent`
`Agents::HTTPRequestAgent`
`Agents::IMAPAgent`
`Agents::LLMAgent`
`Agents::TriggerAgent`
`Agents::WebhookAgent`
`Agents::SendToStoryAgent`
| | agent_options | JSON object with action options. | | folder_id | **Optional** ID of the folder to place the template in. Set to `null` to remove from a folder. The folder must be a template folder belonging to the same team. Unchanged if omitted. | | read_access | **Optional** Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). Unchanged if omitted. (`SPECIFIC_TEAMS` is a premium feature. [Reach out to find out more](https://tines.com/contact-support).) | | shared_team_slugs | **Optional** List of teams' slugs where this template can be used. Required when setting `read_access` to `SPECIFIC_TEAMS`. Unchanged if omitted. | | action_inputs | **Optional** Array of input parameters for the template. Replaces existing inputs when provided. Omit to keep existing inputs unchanged. See [action_inputs structure](#action-inputs-structure) below. | | Path Parameter | Description | | -------------- | ------------------- | | template_id | ID of the template. | ```bash curl -X PUT \ https:///api/v1/admin/templates/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>'\ -d '{ "name": "Name+Update", "description": "test+Update", "agent_type": "Agents::EmailAgent", "vendor": "API+Update", "product": "API+Update", "agent_options": { "mode": "extract+Update", "matchers": [ { "path": "{{.text}}", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "{{.text}}", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message+Update" }, "read_access": "SPECIFIC_TEAMS", "shared_team_slugs": ["team-slug-1", "team-slug-2"], "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "Updated input description", "required": true } ] }' ``` ## Response A successful request will return the updated template with a `200` status. ### Field description | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | id | Template ID. | | name | Template name. | | description | Template description. | | agent_type | Type of action associated with the template. | | agent_options | Action options. | | vendor | Vendor name. | | product | Product name. | | team_id | ID of team to which the template belongs. | | folder_id | ID of the folder containing the template, or `null` if the template is not in a folder. | | read_access | Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this template can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | action_inputs | **Optional** Array of input parameters for the template. See details below. | ### action_inputs structure Each object in the `action_inputs` array can have the following fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------- | | name | **Required** Input parameter name. | | type | **Required** Input type. One of: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `OBJECT`, `OPTION`, `CODE`, `CREDENTIAL`. | | required | Whether the input is required. Defaults to `false`. Must be `true` for `CREDENTIAL` type. | | description | **Optional** Description of the input parameter. | | default_value | **Optional** Default value for the input. | | data | **Optional** Type-specific configuration object. See below. | The `data` object varies by type: _Note: The `data` field is only applicable to `OBJECT`, `OPTION` and `CODE` types. Other types do not use this field._ | Type | data fields | | ------ | ------------------------------------------------------------------------- | | OBJECT | `json_schema`: JSON schema for validation. | | OPTION | `options`: Array of option values. `multi_select_enabled`: Boolean. | | CODE | `code_language`: Language for syntax highlighting (e.g., `HTML`, `JSON`). | #### Type-specific default_value types | Type | Expected default_value type | | ---------- | ------------------------------------- | | TEXT | String | | NUMBER | Integer (or formula string) | | BOOLEAN | Boolean (or formula string) | | DATE | String | | OBJECT | Any valid JSON value | | OPTION | Array (or formula string) | | CODE | String | | CREDENTIAL | Not supported (field must be omitted) | _Formula strings start with `=` (e.g., `=INPUT.name`) or `\\=` for escaped formulas._ #### CREDENTIAL type restrictions `CREDENTIAL` inputs only accept `name`, `type`, and `required` fields. The `description`, `default_value`, and `data` fields are not permitted and will cause a validation error if included. ### Validation constraints The following constraints are enforced when updating a template with `action_inputs`: - **Maximum of 300** action inputs per template. - **Only one** `CREDENTIAL` input is allowed per template. - Input **names must be unique** across all action inputs. - `CREDENTIAL` inputs must have `required` set to `true`. ### Sample response ```json { "id": 472463921472463921, "name": "Name+Update", "description": "test+Update", "agent_type": "Agents::EmailAgent", "agent_options": { "mode": "extract+Update", "matchers": [ { "path": "{{.text}}", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "{{.text}}", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message+Update" }, "vendor": "API+Update", "product": "API+Update", "team_id": 1, "folder_id": 42, "read_access": "SPECIFIC_TEAMS", "shared_team_slugs": ["team-slug-1", "team-slug-2"], "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "Updated input description", "required": true } ] } ``` #### List ## Description Retrieve a list of private templates. Optionally search to filter results. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------ | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | search | **Optional** A search query to filter templates. Matches against name, description, vendor, product, and action options. | | folder_id | **Optional** Filter templates by folder. Only returns templates in the specified folder. | ### List all templates ```bash curl -X GET \ https:///api/v1/admin/templates \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Search templates ```bash curl -X GET \ https:///api/v1/admin/templates \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"search": "Test"}' ``` ### List templates in a folder ```bash curl -X GET \ https:///api/v1/admin/templates?folder_id=<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array of private templates in the Tines tenant. ### Field description | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | id | Template ID. | | name | Template name. | | description | Template description. | | agent_type | Type of action associated with the template. | | agent_options | Action options. | | vendor | Vendor name. | | product | Product name. | | team_id | ID of team to which the template belongs. | | folder_id | ID of the folder containing the template, or `null` if the template is not in a folder. | | read_access | Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this template can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | action_inputs | **Optional** Array of input parameters for the template. See details below. | ### action_inputs structure Each object in the `action_inputs` array can have the following fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------- | | name | **Required** Input parameter name. | | type | **Required** Input type. One of: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `OBJECT`, `OPTION`, `CODE`, `CREDENTIAL`. | | required | Whether the input is required. Defaults to `false`. Must be `true` for `CREDENTIAL` type. | | description | **Optional** Description of the input parameter. | | default_value | **Optional** Default value for the input. | | data | **Optional** Type-specific configuration object. See below. | The `data` object varies by type: _Note: The `data` field is only applicable to `OBJECT`, `OPTION` and `CODE` types. Other types do not use this field._ | Type | data fields | | ------ | ------------------------------------------------------------------------- | | OBJECT | `json_schema`: JSON schema for validation. | | OPTION | `options`: Array of option values. `multi_select_enabled`: Boolean. | | CODE | `code_language`: Language for syntax highlighting (e.g., `HTML`, `JSON`). | ### Sample response ```json { "admin/templates": [ { "id": "472463921472463921", "name": "Extract some text", "description": "test", "agent_type": "Agents::EventTransformationAgent", "agent_options": { "mode": "extract", "matchers": [ { "path": "{{.text}}", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "{{.text}}", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message" }, "vendor": "API", "product": "API", "team_id": 1, "folder_id": 42, "read_access": "TEAM", "shared_team_slugs": [], "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "The text to extract from", "required": true, "default_value": "Sample text" }, { "name": "output_format", "type": "OPTION", "description": "Output format selection", "required": false, "data": { "options": ["JSON", "CSV", "Plain Text"], "multi_select_enabled": false } } ] } ], "meta": { "current_page": "https:///api/v1/admin/templates?page=1&per_page=20", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 1 } } ``` #### Delete ## Description Delete a private template by ID. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ------------------- | | template_id | ID of the template. | ```bash curl -X DELETE \ https:///api/v1/admin/templates/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Move ## Description Move a private template to a different team. > **Warning:** > > - Moving a template to a team will reset its access settings to team-only visibility. > - Resources and credentials used in the template may not exist in the target team. ## Request HTTP Method: **POST** | Path Parameter | Description | | -------------- | ------------------- | | template_id | ID of the template. | | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | **Required** ID of the team to move the template to. | | folder_id | **Optional** ID of a folder on the target team to place the template in. The folder must be a template folder belonging to the target team. | ```bash curl -X POST \ https:///api/v1/admin/templates/<>/move \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"team_id": "<>"}' ``` ## Response A successful request will return the updated template. ### Field description | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | id | Template ID. | | name | Template name. | | description | Template description. | | agent_type | Type of action associated with the template. | | agent_options | Action options. | | vendor | Vendor name. | | product | Product name. | | team_id | ID of team to which the template belongs. | | folder_id | ID of the folder containing the template, or `null` if the template is not in a folder. | | read_access | Control where this template can be used (`TEAM`, `GLOBAL`, `SPECIFIC_TEAMS`). | | shared_team_slugs | List of teams' slugs where this template can be used when `read_access` is `SPECIFIC_TEAMS`, otherwise empty. | | action_inputs | **Optional** Array of input parameters for the template. See details below. | ### action_inputs structure Each object in the `action_inputs` array can have the following fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------------------------------- | | name | **Required** Input parameter name. | | type | **Required** Input type. One of: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `OBJECT`, `OPTION`, `CODE`, `CREDENTIAL`. | | required | Whether the input is required. Defaults to `false`. Must be `true` for `CREDENTIAL` type. | | description | **Optional** Description of the input parameter. | | default_value | **Optional** Default value for the input. | | data | **Optional** Type-specific configuration object. See below. | The `data` object varies by type: _Note: The `data` field is only applicable to `OBJECT`, `OPTION` and `CODE` types. Other types do not use this field._ | Type | data fields | | ------ | ------------------------------------------------------------------------- | | OBJECT | `json_schema`: JSON schema for validation. | | OPTION | `options`: Array of option values. `multi_select_enabled`: Boolean. | | CODE | `code_language`: Language for syntax highlighting (e.g., `HTML`, `JSON`). | ### Sample response ```json { "id": 141, "name": "Extract some text", "description": "test", "agent_type": "Agents::EventTransformationAgent", "agent_options": { "mode": "extract", "matchers": [ { "path": "", "regexp": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b", "to": "email_addresses" }, { "path": "", "regexp": "https?:\\/\\/[\\S]+", "to": "urls" } ], "message": "This is an optional message" }, "vendor": "API", "product": "API", "team_id": 2, "folder_id": null, "read_access": "TEAM", "shared_team_slugs": [], "action_inputs": [ { "name": "input_text", "type": "TEXT", "description": "The text to extract from", "required": true, "default_value": "Sample text" } ] } ``` ### Tunnels #### Health ## Description Retrieve the health status of tunnels. Note: A user must be an admin in order to access this endpoint i.e. a tenant-level API key is required. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | tunnel_name | **Required** Include the name of your tunnel | | per_page | **Optional** Set the number of results returned per page. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | ```bash curl -X GET \ https:///api/v1/admin/tunnel/<>/health \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` Here `tunnel_name` is the name of your tunnel ## Response A successful request will return a JSON object describing the health of the Tunnel. There is more information about health statuses in our Tunnel FAQ page here : https://www.tines.com/docs/admin/tunnel/tunnel-faqs/ ### Field description | Parameter | Description | | --------- | ---------------------------------------------------------------------------- | | health | The health of the tunnel. Accepted values: Down, Healthy, Inactive, Degraded | | name | The team name. | ### Sample response ```json { "health": "Healthy" } ``` ### Users #### Create ## Description Create a user in a Tines tenant. ## Request HTTP Method: **POST** | Query Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | email | User email. | | first_name | **Optional** User first name. | | last_name | **Optional** User last name. | | admin | **Optional** Boolean flag indicating whether user should be admin. Default is false. | | tenant_permissions | **Optional** Array of tenant permission names, from the [list of available permissions](https://www.tines.com/docs/admin/user-administration/#tenant-permissions). | | is_active | **Optional** Boolean flag indicating whether user is active. Default is true. | ### Sample request ```bash curl -X POST \ https:///api/v1/admin/users \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "email": "alice@tines.xyz", "first_name": "Alice", "last_name": "Smith", "admin": false, "tenant_permissions": ["AUDIT_LOG_READ"] }' ``` ## Response A successful request will return a JSON object describing the created user. ### Field description | Parameter | Description | | ------------------ | ----------------------------------------------------------------- | | id | User ID. | | scim_uid | SCIM User ID. | | email | User email. | | admin | Boolean flag indicating whether user is an admin. | | tenant_permissions | Array of tenant permission names. | | is_active | Boolean flag indicating whether user is active. | | created_at | Timestamp describing when the user was created. | | updated_at | Timestamp describing when the user was last updated. | | first_name | User first name. | | last_name | User last name. | | last_seen | Timestamp describing when the user was last seen in the platform. | ### Sample response ```json { "id": 276, "scim_uid": null, "email": "alice@tines.xyz", "created_at": "2019-11-03T09:57:49.537Z", "updated_at": "2019-11-03T09:57:49.537Z", "admin": false, "is_active": true, "first_name": "Alice", "last_name": "Smith", "last_seen": null, "tenant_permissions": ["AUDIT_LOG_READ"] } ``` #### Get ## Description Retrieve details of a specific user. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | --------------- | | user_id | ID of the user. | | Query Parameter | Description | | --------------- | ---------------------------------------- | | include | **Optional** Include: `team_memberships` | ```bash curl -X GET \ https:///api/v1/admin/users/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` Or, to include `team_memberships`: ```bash curl -X GET \ https:///api/v1/admin/users/<>?include=team_memberships \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the User. ### Field description | Parameter | Description | | ------------------ | ----------------------------------------------------------------- | | id | User ID. | | scim_uid | SCIM User ID. | | email | User email. | | admin | Boolean flag indicating whether user is an admin. | | tenant_permissions | Array of tenant permission names. | | is_active | Boolean flag indicating whether user is active. | | created_at | Timestamp describing when the user was created. | | updated_at | Timestamp describing when the user was last updated. | | first_name | User first name. | | last_name | User last name. | | last_seen | Timestamp describing when the user was last seen in the platform. | If `?include=team_memberships` is included, a successful response will include a JSON array of the following: | Parameter | Description | | --------- | ------------------------- | | team_id | Team ID. | | team_name | Team name. | | role | User's role in this team. | ### Sample response ```json { "id": 2, "scim_uid": "123", "email": "alice@tines.xyz", "created_at": "2019-07-08T14:16:11.967Z", "updated_at": "2019-10-31T21:40:52.682Z", "admin": false, "is_active": true, "first_name": "Alice", "last_name": "Smith", "last_seen": "2019-10-31T21:40:42.000Z", "tenant_permissions": ["AUDIT_LOG_READ"] } ``` Or, if `?include=team_memberships` is included in the request: ```json { ..., "team_memberships": [ { "team_id": 7, "team_name": "Security Ops", "role": "EDITOR" }, { "team_id": 12, "team_name": "IR Cases", "role": "CASE_MANAGER" } ] } ``` #### Get sign-in 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](https://www.tines.com/api/audit-logs/list). ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | before | **Optional** Only include logins created before this timestamp | | after | **Optional** Only include logins created after this timestamp | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | Path Parameter | Description | | -------------- | --------------- | | user_id | ID of the user. | ```bash curl -X GET \ https:///api/v1/admin/users/<>/signin_activities \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array describing login events by the specified user. ### Field description | Parameter | Description | | ---------- | ------------------------------------------- | | id | Signin Activity ID. | | user_id | Id of user that signed in | | user_agent | User agent string of client used to sign in | | ip | IP address of signin | | created_at | Timestamp describing when user logged in | ### Sample response ```json { "admin/login_activities": [ { "created_at": "2022-10-19T14:25:18Z", "id": 220, "user_id": 72, "ip": "192.158.1.38", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36" }, { "created_at": "2022-10-19T14:25:18Z", "id": 219, "user_id": 72, "ip": "2001:db8:3333:4444:5555:6666:7777:8888", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36" } ], "meta": { "current_page": "https:///api/v1/admin/users/72/signin_activities?per_page=20&page=1", "previous_page": null, "next_page": "https:///api/v1/admin/users/72/signin_activities?per_page=20&page=2", "next_page_number": 2, "per_page": 20, "pages": 2, "count": 25 } } ``` #### Update ## Description Update a User. ## Request HTTP Method: **PUT** | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | email | **Optional** User email. | | first_name | **Optional** User first name. | | last_name | **Optional** User last name. | | admin | **Optional** Boolean flag indicating whether user should be admin. Default is false. | | tenant_permissions | **Optional** Array of tenant permission names, from the [list of available permissions](https://www.tines.com/docs/admin/user-administration/#tenant-permissions). | | is_active | **Optional** Boolean flag indicating whether user should be active. Default is true. | | Path Parameter | Description | | -------------- | --------------- | | user_id | ID of the user. | ### Sample request ```bash curl -X PUT \ https:///api/v1/admin/users/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' -d '{ "admin": true, "last_name": "Bloggs" }' ``` ## Response A successful request will return a JSON object describing the updated user. ### Field description | Parameter | Description | | ------------------ | ----------------------------------------------------------------- | | id | User ID. | | scim_uid | SCIM User ID. | | email | User email. | | admin | Boolean flag indicating whether user is an admin. | | tenant_permissions | Array of tenant permission names. | | is_active | Boolean flag indicating whether user is active. | | created_at | Timestamp describing when the user was created. | | updated_at | Timestamp describing when the user was last updated. | | first_name | User first name. | | last_name | User last name. | | last_seen | Timestamp describing when the user was last seen in the platform. | ### Sample response ```json { "id": 3, "scim_uid": null, "email": "alice@tines.xyz", "created_at": "2019-11-03T09:57:49.537Z", "updated_at": "2019-11-03T09:57:49.537Z", "admin": true, "is_active": true, "first_name": "Alice", "last_name": "Bloggs", "last_seen": null, "tenant_permissions": null } ``` #### List ## Description Retrieve a list of users from the Tines tenant. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------- | | per_page | **Optional** Set the number of results returned per page. Defaults to 20. | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | | filter | **Optional** Filter: `TENANT_OWNER` | | include | **Optional** Include: `team_memberships` | ```bash curl -X GET \ https:///api/v1/admin/users \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON Array of users in the Tines tenant. ### Field description | Parameter | Description | | ------------------ | ----------------------------------------------------------------- | | id | User ID. | | scim_uid | SCIM User ID. | | email | User email. | | admin | Boolean flag indicating whether user is an admin. | | tenant_permissions | Array of tenant permission names. | | is_active | Boolean flag indicating whether user is active. | | created_at | Timestamp describing when the user was created. | | updated_at | Timestamp describing when the user was last updated. | | first_name | User first name. | | last_name | User last name. | | last_seen | Timestamp describing when the user was last seen in the platform. | If `?include=team_memberships` is included, a successful response will include the following JSON array for each User: | Parameter | Description | | --------- | ------------------------- | | team_id | Team ID. | | team_name | Team name. | | role | User's role in this team. | ### Sample response ```json { "admin/users": [ { "id": 2, "scim_uid": null, "email": "alice@tines.xyz", "created_at": "2019-07-08T14:16:11.967Z", "updated_at": "2019-10-31T21:40:52.682Z", "admin": false, "is_active": true, "first_name": "Alice", "last_name": "Smith", "last_seen": "2019-10-31T21:40:42.000Z", "tenant_permissions": ["AUDIT_LOG_READ"] }, { "id": 3, "scim_uid": null, "email": "joe@tines.xyz", "created_at": "2019-09-11T14:46:37.880Z", "updated_at": "2019-09-27T20:45:46.527Z", "admin": false, "is_active": true, "first_name": "Joe", "last_name": "Bloggs", "last_seen": "2019-09-27T20:45:46.000Z", "tenant_permissions": [] } ], "meta": { "current_page": "https:///api/v1/admin/users?page=1&per_page=20", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` Or, if `?include=team_memberships` is included in the request: ```json { "admin/users": [ { ..., "team_memberships": [ { "team_id": 7, "team_name": "Security Ops", "role": "EDITOR" }, { "team_id": 12, "team_name": "IR Cases", "role": "CASE_MANAGER" } ] } ], "meta": { "current_page": "https:///api/v1/admin/users?page=1&per_page=20", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` #### Delete ## Description Delete a specific user. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | --------------- | | user_id | ID of the user. | ```bash curl -X DELETE \ https:///api/v1/admin/users/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. #### Resend invitation ## Description Resend platform invitation to specified user. ## Request HTTP Method: **POST** | Path Parameter | Description | | -------------- | ------------------------------------ | | user_id | ID of the user to resend invitation. | ```bash curl -X POST \ https:///api/v1/admin/users/<>/resend_invitation \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return either an empty response or a message stating `User already accepted invitation.` both with a `200` status code. ### Sample response ```json { "message": "User already accepted invitation." } ``` #### Expire session ## Description Expires a user’s session, signing them out of the Tines tenant on all devices. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | --------------- | | user_id | ID of the user. | ```bash curl -X POST \ https:///api/v1/admin/users/<>/expire_session \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ## Dashboards ### List ## Description Retrieve a paginated list of dashboards. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | **Optional** Only return dashboards belonging to this team. | | order | **Optional** Order the results by one of: `NAME`, `RECENTLY_CREATED`, `RECENTLY_UPDATED`. Defaults to `NAME` when not specified or invalid. | | per_page | **Optional** Set the number of results returned per page. Defaults to 20, maximum is 500. | | page | **Optional** The page number of results to fetch. Defaults to page 1. | ```bash curl -X GET \ "https:///api/v1/dashboards?team_id=1&order=RECENTLY_UPDATED" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the dashboards the requesting token has access to. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------- | | id | The ID of the dashboard. | | name | Name of the dashboard. | | team | Object describing the team this dashboard belongs to. | | team.id | Integer ID of the team. | | team.name | Name of the team. | | created_at | ISO 8601 timestamp representing when the dashboard was created. | | updated_at | ISO 8601 timestamp representing when the dashboard was last updated. | ### Sample response ```json { "dashboards": [ { "id": 1, "name": "Example dashboard", "team": { "id": 2, "name": "Audits" }, "created_at": "2026-02-18T19:38:13Z", "updated_at": "2026-02-18T21:53:21Z" }, { "id": 2, "name": "Imported dashboard", "team": { "id": 3, "name": "Triage" }, "created_at": "2026-03-10T17:47:52Z", "updated_at": "2026-03-10T17:47:52Z" } ], "meta": { "current_page": "http:///api/v1/dashboards?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Delete ## Description Delete a dashboard. ## Request HTTP Method: **DELETE** | Parameter | Description | | ------------ | ---------------------------------- | | dashboard_id | The ID of the dashboard to delete. | ```bash curl -X DELETE \ https:///api/v1/dashboards/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return an empty response with a `204` status code. ### Export ## Description Export a dashboard. The response can be passed to the import endpoint to recreate the dashboard in another team or tenant. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ---------------------------------- | | id | The ID of the dashboard to export. | ```bash curl -X GET \ https:///api/v1/dashboards/<>/export \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the dashboard in exported form. ### Field description | Parameter | Description | | -------------- | -------------------------------------------------------------- | | schema_version | The version of the export schema format. | | export_type | The type of the export, "dashboard". | | exported_at | ISO 8601 timestamp representing when the export was generated. | | dashboard | Object containing the dashboard configuration. | ### Sample response ```json { "schema_version": 1, "export_type": "dashboard", "exported_at": "2025-02-10T12:30:45Z", "dashboard": { "name": "Security overview", "notes": [ { "id": "a1b2c3d4e5f6", "name": "Welcome note", "content": "This dashboard shows key security metrics." } ], "case_lists": [ { "id": "b2c3d4e5f6a1", "name": "Open cases", "type": "cases", "color_palette": "default", "filters": {}, "options": {} } ], "record_charts": [ { "id": "c3d4e5f6a1b2", "name": "Priority breakdown", "record_type_name": "Cases", "element_type": "chart", "axes": [ { "direction": "x", "record_field_name": "priority" } ], "aggregation": "COUNT", "rolling_date_range": null, "range_start": null, "range_end": null, "filters": { "stories": [], "fields": [ { "value": "open", "operator": "equals", "name": "status" } ] }, "order": { "field": null, "direction": null }, "color_palette": "default", "options": {}, "record_fields": [], "test_mode": false } ], "layout": [ { "i": "a1b2c3d4e5f6", "x": 0, "y": 0, "w": 12, "h": 2 }, { "i": "b2c3d4e5f6a1", "x": 0, "y": 2, "w": 6, "h": 4 }, { "i": "c3d4e5f6a1b2", "x": 6, "y": 2, "w": 6, "h": 4 } ] } } ``` ### Import ## Description Import a dashboard. The import data should be obtained from the [export endpoint](/api/dashboards/export). ## Request HTTP Method: **POST** | Body Parameter | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | team_id | ID of the team to which the dashboard should be added. | | data | JSON object representing the dashboard in [exported form](/api/dashboards/export#sample-response). | | mode | **Optional** Create a new dashboard or replace an existing one by name - (`new`, `replace`). Defaults to `new`. | | new_name | **Optional** Name for the dashboard. Defaults to the name in the export data. In `replace` mode, this specifies which existing dashboard to replace. | ```bash curl -X POST \ https:///api/v1/dashboards/import \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "team_id": 14, "new_name": "Imported dashboard", "mode": "new", "data": { "schema_version": 1, "dashboard": { "name": "Security overview", "notes": [ { "id": "a1b2c3d4e5f6", "name": "Welcome note", "content": "This dashboard shows key security metrics." } ], "case_lists": [ { "id": "b2c3d4e5f6a1", "name": "Open cases", "type": "cases", "color_palette": "default", "filters": {}, "options": {} } ], "record_charts": [ { "id": "c3d4e5f6a1b2", "name": "Priority breakdown", "record_type_name": "Cases", "element_type": "chart", "axes": [ { "direction": "x", "record_field_name": "priority" } ], "aggregation": "COUNT", "rolling_date_range": null, "range_start": null, "range_end": null, "filters": { "stories": [], "fields": [ { "value": "open", "operator": "equals", "name": "status" } ] }, "order": { "field": null, "direction": null }, "color_palette": "default", "options": {}, "record_fields": [], "test_mode": false } ], "layout": [ { "i": "a1b2c3d4e5f6", "x": 0, "y": 0, "w": 12, "h": 2 }, { "i": "b2c3d4e5f6a1", "x": 0, "y": 2, "w": 6, "h": 4 }, { "i": "c3d4e5f6a1b2", "x": 6, "y": 2, "w": 6, "h": 4 } ] } } }' ``` ## Response A successful request will return a JSON object describing the newly created dashboard with a `201` status code. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------- | | id | The ID of the dashboard. | | name | Name of the dashboard. | | team | Object describing the team this dashboard belongs to. | | team.id | Integer ID of the team. | | team.name | Name of the team. | | created_at | ISO 8601 timestamp representing when the dashboard was created. | | updated_at | ISO 8601 timestamp representing when the dashboard was last updated. | ### Sample response ```json { "id": 42, "name": "Imported dashboard", "team": { "id": 14, "name": "Security Operations" }, "created_at": "2025-02-14T10:30:00Z", "updated_at": "2025-02-14T10:30:00Z" } ``` ## Info ### GET ## Description Retrieve basic information regarding your tenant's stack. ## Request HTTP Method: **GET** ```bash curl -X GET \ https:///api/v1/info \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the information related to your tenant's stack. ### Field description | Parameter | Description | | ---------- | -------------------------------------------------------------------------- | | stack | An object containing the stack information. | | name | The name assigned to the tenant's stack. | | type | Whether the stack is dedicated or shared. | | region | The AWS region that the stack is hosted in. | | egress_ips | The origin IPs that are used for any request originating from your tenant. | ### Sample response ```json { "stack": { "name": "stackName", "type": "shared", "region": "eu-west-1", "egress_ips": ["192.168.0.1", "192.168.0.2"] } } ``` ### GET Web Statistics ## 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. **Note:** This endpoint is accessible only to self-hosted customers. ## Request HTTP Method: **GET** ```bash curl -X GET \ https:///api/v1/info/web_stats \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing information about Puma web server status. See https://puma.io/puma/file.stats.html for details. ### Sample Response ```json { "started_at": "2025-03-06T10:10:14Z", "backlog": 0, "running": 16, "pool_capacity": 15, "busy_threads": 1, "max_threads": 16, "requests_count": 2057, "versions": { "puma": "6.6.0", "ruby": { "engine": "ruby", "version": "3.4.2", "patchlevel": 28 } } } ``` ### GET Worker Statistics ## Description Retrieve essential information about worker statistics. **Note:** This endpoint is accessible only to self-hosted customers. ## Request HTTP Method: **GET** ```bash curl -X GET \ https:///api/v1/info/worker_stats \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing the information related to worker statistics. ### Field description | Parameter | Description | | --------------- | -------------------------------------- | | current_workers | The number of active workers. | | max_workers | The maximum number of workers allowed. | | queue_count | The total count of items in the queue. | | queue_latency | The latency of the default queue. | ### Sample Response ```json { "current_workers": 10, "max_workers": 20, "queue_count": 100, "queue_latency": 500 } ``` ## SCIM ## About SCIM Tines provides [SCIM v2.0](https://simplecloud.info/)-compliant endpoints to enable synchronization with Identity Providers (IdPs) that support this standard. ## Configuration These endpoints are only available for tenants with plans that include the SCIM feature and have enabled SCIM (in the tenant's Authentication settings). ## Endpoints The base endpoint for SCIM operations (this is what needs to be configured in most IdPs) is `https:///api/scim/v2` All endpoints expect the `application/scim+json` Content type. | Verb | Path | Description | | -------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `GET` | `/api/scim/v2/ServiceProviderConfig` | Show Configurations | | `GET` | `/api/scim/v2/ResourceTypes` | Index Resource Types | | `GET` | `/api/scim/v2/ResourceTypes/:name ` | Show Resource Type | | `GET` | `/api/scim/v2/Schemas` | Index Schemas | | `GET` | `/api/scim/v2/Users` | Index Users | | `GET` | `/api/scim/v2/Users/:id` | Show User | | `POST` | `/api/scim/v2/Users` | Create User | | `PUT` | `/api/scim/v2/Users/:id` | Replace User | | `PATCH` | `/api/scim/v2/Users/:id` | Update User | | `DELETE` | `/api/scim/v2/Users/:id` | Disable User. Use the UI or [this API endpoint](/api/admin/users/delete) to completely delete a user. | | `GET` | `/api/scim/v2/Groups` | Index Groups | | `GET` | `/api/scim/v2/Groups/:id` | Show Group | | `POST` | `/api/scim/v2/Groups` | Create Group | | `PUT` | `/api/scim/v2/Groups/:id` | Replace Group | | `PATCH` | `/api/scim/v2/Groups/:id` | Update Group | | `DELETE` | `/api/scim/v2/Groups/:id` | Destroy Group | ## Authentication Authentication for all endpoints follows the same scheme as the rest of the API (described in the Authentication section). Only API keys with tenant owner access can be used for SCIM. ## Supported attributes ### Users | name | Type | Description | | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------------------- | | `userName` | `string` | The username for the user. It must be the user's email. | | `name.givenName` | `string` | The first name of the user. | | `name.familyName` | `string` | The last name of the user. | | `externalId` | `string` | This identifier is generated by the IdP provider. | | `id` | `string` | Identifier generated by Tines. | | `active` | `boolean` | Whether the identity is active (true) or not (false). | | `userType` | `string` | `"TENANT_OWNER"` (also known as `admin: true` in the Tines API User schema) or `"USER"`. | | `groups` | `ComplexType` | Array of groups this user belongs to. This field is immutable and must be changed by updating each Group's `members`. | ### Groups | name | Type | Description | | ------------- | ------------- | ---------------------------------------------------- | | `displayName` | `string` | The display name for the group. | | `externalId` | `string` | This identifier is generated by the IdP provider. | | `id` | `string` | Identifier generated by Tines. | | `members` | `ComplexType` | Array of Users and Groups that belong to this Group. | ## Tags ### Create ## Description Create a tag in Tines. ## Request HTTP Method: **POST** | Body Parameter | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------- | | name | Tag name. | | team_id | ID of the team to which the tag belongs. | | color | Tag color. Use one of `purple`, `blue`, `gold`, `green`, `magenta`, `red`, `orange`, `mint`, or a `#RRGGBB` hex value. | ### Sample request ```bash curl -X POST \ https:///api/v1/tags \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "priority-high", "team_id": 1, "color": "red" }' ``` ## Response A successful request will return a JSON object describing the created tag. ### Field description | Parameter | Description | | ---------- | ------------------------------------------------------------------------------------------------ | | id | Tag ID. | | name | Tag name. | | color | Tag color in hex format (for example, `#FF8888`). | | teams | The teams the tag belongs to. Tags created after February 2025 can only belong to a single team. | | created_at | ISO 8601 timestamp describing when the tag was created. | | updated_at | ISO 8601 timestamp describing when the tag was last updated. | ### Sample response ```json { "id": 17, "name": "priority-high", "color": "#FF8888", "teams": [ { "id": 276, "name": "Test team 1" } ], "created_at": "2026-04-10T09:15:42.128Z", "updated_at": "2026-04-10T09:15:42.128Z" } ``` ### Get ## Description Retrieve a single tag. ## Request HTTP Method: **GET** | Path Parameter | Description | | -------------- | ------------------------------ | | tag_id | The ID of the tag to retrieve. | ```bash curl -X GET \ https:///api/v1/tags/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object describing the requested tag. ### Field description | Parameter | Description | | ---------- | ------------------------------------------------------------------------------------------------ | | id | Tag ID. | | name | Tag name. | | color | Tag color in hex format (for example, `#8D75E6`). | | teams | The teams the tag belongs to. Tags created after February 2025 can only belong to a single team. | | created_at | ISO 8601 timestamp describing when the tag was created. | | updated_at | ISO 8601 timestamp describing when the tag was last updated. | ### Sample response ```json { "id": 17, "name": "priority-high", "color": "#FF8888", "teams": [ { "id": 276, "name": "Test team 1" } ], "created_at": "2026-04-10T09:15:42.128Z", "updated_at": "2026-04-10T09:15:42.128Z" } ``` ### Update ## Description Update a tag. ## Request HTTP Method: **PUT** | Path Parameter | Description | | -------------- | ---------------------------- | | tag_id | The ID of the tag to update. | | Body Parameter | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | name | **Optional** Updated tag name. | | color | **Optional** Updated tag color. Use one of `purple`, `blue`, `gold`, `green`, `magenta`, `red`, `orange`, `mint`, or a `#RRGGBB` hex value. | ### Sample request ```bash curl -X PUT \ https:///api/v1/tags/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{ "name": "priority-critical", "color": "#9B61FF" }' ``` ## Response A successful request will return a JSON object describing the updated tag. ### Field description | Parameter | Description | | ---------- | ------------------------------------------------------------------------------------------------ | | id | Tag ID. | | name | Tag name. | | color | Tag color in hex format (for example, `#9B61FF`). | | teams | The teams the tag belongs to. Tags created after February 2025 can only belong to a single team. | | created_at | ISO 8601 timestamp describing when the tag was created. | | updated_at | ISO 8601 timestamp describing when the tag was last updated. | ### Sample response ```json { "id": 17, "name": "priority-critical", "color": "#9B61FF", "teams": [ { "id": 276, "name": "Test team 1" } ], "created_at": "2026-04-10T09:15:42.128Z", "updated_at": "2026-04-10T11:04:03.772Z" } ``` ### List ## Description Retrieve a list of tags. ## Request HTTP Method: **GET** | Query Parameter | Description | | --------------- | --------------------------------------------------------------------- | | team_id | **Optional** Return tags belonging to this team. | | per_page | **Optional** The number of results returned per page. Defaults to 20. | | page | **Optional** The page of results to return. Defaults to 1. | ```bash curl -X GET \ https:///api/v1/tags \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing an array of tags the requesting token has access to. ### Field description | Parameter | Description | | ---------- | ------------------------------------------------------------------------------------------------ | | id | Tag ID. | | name | Tag name. | | color | Tag color in hex format (for example, `#8D75E6`). | | teams | The teams the tag belongs to. Tags created after February 2025 can only belong to a single team. | | created_at | ISO 8601 timestamp describing when the tag was created. | | updated_at | ISO 8601 timestamp describing when the tag was last updated. | ### Sample response ```json { "tags": [ { "id": 17, "name": "priority-high", "color": "#FF8888", "teams": [ { "id": 100, "name": "Test team 1" }, { "id": 101, "name": "Test team 2" } ], "created_at": "2026-04-10T09:15:42.128Z", "updated_at": "2026-04-10T09:15:42.128Z" }, { "id": 18, "name": "triage", "color": "#4BBFFF", "teams": [ { "id": 276, "name": "Test team 3" } ], "created_at": "2026-04-10T09:21:11.491Z", "updated_at": "2026-04-10T09:21:11.491Z" } ], "meta": { "current_page": "https:///api/v1/tags?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ``` ### Delete ## Description Delete a tag. If a `team_id` is provided, the tag will only be deleted for that team. ## Request HTTP Method: **DELETE** | Path Parameter | Description | | -------------- | ---------------------------- | | tag_id | The ID of the tag to delete. | | Query Parameter | Description | | --------------- | --------------------------------------------------- | | team_id | **Optional** ID of the team to remove the tag from. | ### Sample request ```bash curl -X DELETE \ https:///api/v1/tags/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' \ -d '{"team_id": 5}' ``` ## Response A successful request will return an empty response with a `204` status code. ## Workbench ### Get ## Description Retrieve a workbench conversation. ## Request HTTP Method: **GET** | Parameter | Description | | --------- | ----------------------------------------- | | guid | The GUID of the conversation to retrieve. | ```bash curl -X GET \ https:///api/v1/workbench/<> \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object representing the specified workbench conversation. ### Field description | Parameter | Description | | --------- | ----------------------------------------------------------------------------------- | | guid | The conversation GUID. | | steps | An array of conversation messages including user, assistant, and tool interactions. | ### Sample response ```json { "guid": "ca68403e-5594-42a4-bec7-879b0b417a83", "steps": [ { "role": "user", "contents": [ { "text": "what is the weather in dublin", "type": "text" } ] }, { "role": "assistant", "contents": [ { "type": "text", "text": "I'll check the current weather in Dublin for you." } ] }, { "role": "tool", "name": "simple_weather_api_get_weather_at_location", "inputs": { "location": "Dublin" }, "output": { "body": { "dt": 1750408079, "uvi": 2.32, "temp": 294.61, "clouds": 75, "sunset": 1750453002, "sunrise": 1750391791, "weather": [ { "id": 803, "icon": "04d", "main": "Clouds", "description": "broken clouds" } ], "humidity": 63, "location": "Dublin", "pressure": 1020, "wind_deg": 140, "dew_point": 287.28, "feels_like": 294.46, "visibility": 10000, "wind_speed": 4.12 }, "meta": { "response_time": 2.341445 }, "status": 200, "headers": { "date": "Fri, 20 Jun 2025 08:28:00 GMT", "connection": "keep-alive", "content-type": "application/json; charset=utf-8", "x-request-id": "27f3829f-b8d3-462b-926d-887922459c36", "cache-control": "max-age=0, private, must-revalidate", "content-length": "318", "x-tines-status": "data_received", "referrer-policy": "strict-origin-when-cross-origin", "x-frame-options": "SAMEORIGIN", "x-tines-event-id": "198402032", "x-tines-revision": "47076c83", "x-xss-protection": "0", "x-download-options": "noopen", "content-disposition": "inline", "x-content-type-options": "nosniff", "x-tines-exit-action-id": "145208", "content-security-policy": "default-src 'none'", "x-tines-response-location": "https://v1.simple-weather-api.com/api/public/weather/result/yFb6cLyLoY0SZRpevrYCQg==", "x-permitted-cross-domain-policies": "none" } } }, { "role": "assistant", "contents": [ { "type": "text", "text": "Currently in Dublin, it's 21.46°C (70.63°F) with broken clouds. The humidity is at 63% with a wind speed of 4.12 m/s from the southeast (140°). Visibility is good at 10 km, and the air pressure is 1020 hPa. The sun rose at 5:43 AM and will set at 9:50 PM local time." } ] }, { "role": "user", "contents": [ { "text": "thanks workbench", "type": "text" } ] }, { "role": "assistant", "contents": [ { "type": "text", "text": "You're welcome! Let me know if you need any other information." } ] } ] } ``` ### List ## Description List workbench conversations. ## Request HTTP Method: **GET** | Parameter | Description | Required | Type | | ---------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | | search | **Optional** Search term to filter conversations by title | No | String | | favorited | **Optional** Filter by favorited status (true/false) | No | Boolean | | creator_id | **Optional** Filter conversations by the ID of the creator (user) | No | String | | per_page | **Optional** Set the number of results returned per page | No | Integer | | page | **Optional** Specify the page of results to return if there are multiple pages. Defaults to page 1. | No | Integer | ```bash curl -X GET \ "https:///api/v1/workbench?per_page=20&page=1&search=weather&favorited=true" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ## Response A successful request will return a JSON object containing a paginated list of workbench conversations. ### Field description | Parameter | Description | | ------------- | --------------------------------------------------------- | | conversations | Array of Workbench conversation objects | | guid | The conversation GUID | | title | The conversation title | | source | The source of the conversation | | favorited | Whether the conversation is favorited by the user | | creator_id | The ID of the user who created the conversation | | created_at | ISO 8601 timestamp when the conversation was created | | updated_at | ISO 8601 timestamp when the conversation was last updated | ### Sample response ```json { "conversations": [ { "guid": "ca68403e-5594-42a4-bec7-879b0b417a83", "title": "Reset user password", "source": "tines", "favorited": true, "creator_id": "12345", "created_at": "2025-06-20T08:25:30Z", "updated_at": "2025-06-20T08:30:15Z" }, { "guid": "b8f2c1a3-9876-4321-a1b2-c3d4e5f6789a", "title": "Data analysis discussion", "source": "slack", "favorited": false, "creator_id": "12345", "created_at": "2025-06-19T14:20:10Z", "updated_at": "2025-06-19T16:45:22Z" } ], "meta": { "current_page": "https:///api/v1/workbench?per_page=20&page=1", "previous_page": null, "next_page": "https:///api/v1/workbench?per_page=20&page=2", "next_page_number": 2, "per_page": 20, "pages": 3, "count": 42 } } ``` ### Pagination This endpoint supports page-based pagination using the `per_page` and `page` parameters: - Use `per_page` to specify the number of results per page - Use `page` to specify which page of results to return (defaults to 1) - The response includes a `meta` object with pagination information including total count and page links ### Filtering - **search**: Filters conversations containing the search term in their title - **favorited**: Set to `true` to only return favorited conversations, `false` for non-favorited, or omit for all - **creator_id**: Only return conversations created by the specified user ID