openapi: 3.0.3
info:
  title: Tines REST Actions Folders API
  description: The Tines REST API provides programmatic access to all platform resources including stories (workflows), actions, credentials, teams, folders, cases, records, dashboards, audit logs, SCIM provisioning, AI usage tracking, reporting, tags, and the workbench. The API uses API key authentication via X-User-Token header or Bearer token and is accessed via each tenant's custom subdomain.
  version: 1.0.0
  contact:
    name: Tines API Documentation
    url: https://www.tines.com/api/welcome/
  x-api-id: tines-rest-api
  x-provider-name: tines
servers:
- url: https://{tenantDomain}/api/v1
  description: Tines tenant API v1
  variables:
    tenantDomain:
      default: your-tenant.tines.com
      description: Your Tines tenant domain (e.g. adjective-noun-1234.tines.com)
- url: https://{tenantDomain}/api/v2
  description: Tines tenant API v2 (Cases)
  variables:
    tenantDomain:
      default: your-tenant.tines.com
      description: Your Tines tenant domain
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Folders
  description: Organize stories, credentials, and resources into folders
paths:
  /folders:
    get:
      operationId: listFolders
      summary: List folders
      description: Returns a paginated list of folders.
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: team_id
        in: query
        description: Filter folders by team ID
        schema:
          type: integer
      responses:
        '200':
          description: Paginated list of folders
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedMeta'
                - type: object
                  properties:
                    folders:
                      type: array
                      items:
                        $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: createFolder
      summary: Create a folder
      description: Creates a new folder to organize stories, credentials, or resources.
      tags:
      - Folders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreate'
            example:
              name: Folder name
              content_type: CREDENTIAL
              team_id: 1
              parent_folder_id: 5
      responses:
        '200':
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
              example:
                id: 1
                name: Folder name
                content_type: CREDENTIAL
                team_id: 1
                size: 0
                parent_folder_id: 5
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /folders/{id}:
    get:
      operationId: getFolder
      summary: Get a folder
      description: Returns details for a specific folder by ID.
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Folder details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      operationId: updateFolder
      summary: Update a folder
      description: Updates an existing folder by ID.
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderCreate'
      responses:
        '200':
          description: Folder updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: deleteFolder
      summary: Delete a folder
      description: Deletes a folder by ID.
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Folder deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    FolderCreate:
      type: object
      required:
      - name
      - content_type
      - team_id
      properties:
        name:
          type: string
          description: The folder name
        content_type:
          type: string
          enum:
          - CREDENTIAL
          - RESOURCE
          - STORY
          description: Accepts CREDENTIAL, RESOURCE, or STORY
        team_id:
          type: integer
          description: ID of team receiving the folder
        parent_folder_id:
          type: integer
          nullable: true
          description: ID of the parent folder; default null (root level)
    Folder:
      type: object
      properties:
        id:
          type: integer
          description: Unique folder identifier
        name:
          type: string
          description: Folder name
        content_type:
          type: string
          enum:
          - CREDENTIAL
          - RESOURCE
          - STORY
          description: Type of content stored in this folder
        team_id:
          type: integer
          description: ID of team to which the folder belongs
        size:
          type: integer
          description: Number of items in this folder
        parent_folder_id:
          type: integer
          nullable: true
          description: ID of the parent folder, or null if at root level
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing the issue
    PaginatedMeta:
      type: object
      properties:
        meta:
          type: object
          properties:
            current_page:
              type: integer
            previous_page:
              type: integer
              nullable: true
            next_page:
              type: integer
              nullable: true
            next_page_number:
              type: integer
              nullable: true
            per_page:
              type: integer
            pages:
              type: integer
            count:
              type: integer
  responses:
    Unauthorized:
      description: Authentication credentials missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Validation error — one or more request parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      description: The unique numeric identifier of the resource
      schema:
        type: integer
    PerPage:
      name: per_page
      in: query
      description: Number of results per page (default 20, max 500)
      schema:
        type: integer
        default: 20
        maximum: 500
    Page:
      name: page
      in: query
      description: Page number for pagination (default 1)
      schema:
        type: integer
        default: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token authentication using an Tines API key. Format: `Authorization: Bearer <api_key>`'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-User-Token
      description: 'API key authentication using the X-User-Token header. Format: `X-User-Token: <api_key>`'