openapi: 3.0.3
info:
  title: Tines REST Actions Teams 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: Teams
  description: Manage teams and team membership
paths:
  /teams:
    get:
      operationId: listTeams
      summary: List teams
      description: Returns a list of teams accessible by the API key.
      tags:
      - Teams
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedMeta'
                - type: object
                  properties:
                    teams:
                      type: array
                      items:
                        $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: createTeam
      summary: Create a team
      description: Creates a new team.
      tags:
      - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The team name
            example:
              name: Security team
      responses:
        '200':
          description: Team created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
              example:
                id: 1
                name: Security team
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /teams/{id}:
    get:
      operationId: getTeam
      summary: Get a team
      description: Returns details for a specific team by ID.
      tags:
      - Teams
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    put:
      operationId: updateTeam
      summary: Update a team
      description: Updates an existing team by ID.
      tags:
      - Teams
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: Team updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: deleteTeam
      summary: Delete a team
      description: Deletes a team by ID.
      tags:
      - Teams
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Team deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing the issue
    Team:
      type: object
      properties:
        id:
          type: integer
          description: Unique team identifier
        name:
          type: string
          description: Team name
    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>`'