Clarify Users API

openapi: 3.2.0
info:
  title: Clarify Users API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
tags:
- name: Users
paths:
  /workspaces/{workspace}/users:
    get:
      description: Returns the workspace’s users as a paginated JSON:API list. Each user includes their roles.
      operationId: getUsers
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: Offset pagination, e.g. `page[offset]=0&page[limit]=100`.
        schema:
          properties:
            offset:
              default: 0
              type: number
              minimum: 0
              description: The number of records to skip before the first result.
              required: false
            limit:
              default: 500
              type: number
              minimum: 1
              maximum: 500
              description: The maximum number of records to return per page (up to 500).
              required: false
          default:
            offset: 0
            limit: 500
          type: object
      - name: sortOrder
        required: false
        in: query
        description: Sort order, e.g. `sortOrder[column]=_created_at&sortOrder[dir]=DESC`.
        schema:
          properties:
            column:
              description: The field name to sort by.
              type: string
              minLength: 1
              required: true
            dir:
              type: string
              enum:
              - ASC
              - DESC
              description: The sort direction.
              required: true
          type: object
      responses:
        '200':
          description: The workspace’s users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfUsersResponse'
              example:
                links:
                  next: null
                  prev: null
                meta:
                  total_records: 1
                  total_pages: 1
                  offset: 0
                  limit: 500
                data:
                - type: user
                  id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                  attributes:
                    _id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    name:
                      first_name: Alex
                      last_name: Rivera
                    roles:
                      items:
                      - member
                    email: alex@acme.com
                    profile_picture: https://storage.clarify.ai/avatars/acme/alex-rivera.png
                    last_active_at: '2026-02-01T17:45:00.000Z'
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: List users
      tags:
      - Users
  /workspaces/{workspace}/users/{userId}:
    get:
      description: Returns a single workspace user as a JSON:API resource, including their roles and the time they were last active.
      operationId: getUser
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: userId
        required: true
        in: path
        description: The unique ID of the user.
        schema:
          type: string
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserResponse'
              example:
                data:
                  type: user
                  id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                  attributes:
                    _id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    name:
                      first_name: Alex
                      last_name: Rivera
                    roles:
                      items:
                      - member
                    email: alex@acme.com
                    profile_picture: https://storage.clarify.ai/avatars/acme/alex-rivera.png
                    last_active_at: '2026-02-01T17:45:00.000Z'
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Get a user
      tags:
      - Users
    delete:
      description: 'Removes a user from the workspace: they lose access, their campaigns stop, and their connected mailboxes disconnect. Their records stay in the workspace. The last user and the last admin cannot be removed.'
      operationId: removeUser
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: userId
        required: true
        in: path
        description: The unique ID of the user.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '204':
          description: The user was removed.
        '400':
          description: The user is the last user or the last admin in the workspace.
        '403':
          description: The caller cannot manage workspace users.
        '404':
          description: The user does not exist.
      security:
      - bearer: []
      summary: Remove a user
      tags:
      - Users
  /workspaces/{workspace}/users/{userId}/role:
    patch:
      description: Sets a workspace user’s role to `admin` or `member` and returns the updated user as a JSON:API resource. Requires an admin signed in with a user access token; the last admin cannot be demoted.
      operationId: updateUserRole
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: userId
        required: true
        in: path
        description: The unique ID of the user.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRoleDto'
            examples:
              promote:
                summary: Make the user an admin
                value:
                  role: admin
      responses:
        '200':
          description: The user with the new role.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUserResponse'
              example:
                data:
                  type: user
                  id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                  attributes:
                    _id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    name:
                      first_name: Alex
                      last_name: Rivera
                    roles:
                      items:
                      - admin
                    email: alex@acme.com
                    profile_picture: https://storage.clarify.ai/avatars/acme/alex-rivera.png
                    last_active_at: '2026-02-01T17:45:00.000Z'
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
        '400':
          description: The change would leave the workspace without an admin.
        '403':
          description: The caller is not a workspace admin, or uses an API key.
        '404':
          description: The user does not exist.
      security:
      - bearer: []
      summary: Change a user’s role
      tags:
      - Users
components:
  schemas:
    UpdateUserRoleDto:
      type: object
      properties:
        role:
          type: string
          enum:
          - admin
          - member
          description: 'The role to assign: `admin` or `member`.'
      required:
      - role
    ListOfUsersResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            next:
              type: string
              nullable: true
              description: URL of the next page, or `null` on the last page.
            prev:
              type: string
              nullable: true
              description: URL of the previous page, or `null` on the first page.
          required:
          - next
          - prev
          description: Pagination links.
        meta:
          type: object
          properties:
            total_records:
              type: number
              description: Total number of records across all pages.
            total_pages:
              type: number
              description: Total number of pages at the current page size.
          required:
          - total_records
          - total_pages
          description: Pagination metadata.
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - user
                description: The resource type; matches the `object` path parameter.
              id:
                type: string
                description: The unique ID of the resource.
              attributes:
                type: object
                properties:
                  _id:
                    type: string
                    description: The unique ID of the user.
                  name:
                    type: object
                    properties:
                      first_name:
                        type: string
                        description: The user’s first name.
                      last_name:
                        type: string
                        description: The user’s last name.
                      full_name:
                        type: string
                        description: The user’s full name (first and last combined).
                    required:
                    - first_name
                    - last_name
                    description: The user’s name.
                  roles:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: string
                          enum:
                          - super_admin
                          - admin
                          - member
                        minItems: 1
                        maxItems: 1
                        description: The user’s role, as a single-element array.
                    required:
                    - items
                    description: The user’s workspace role, as a single-element array. Humans are `admin` or `member`; `super_admin` is reserved for the seeded system service account.
                  email:
                    type: string
                    nullable: true
                    description: The user’s email address.
                  profile_picture:
                    type: string
                    description: A URL to the user’s profile picture.
                  is_service_account:
                    type: boolean
                    description: Server-derived. True for a non-human service account (an account with no identity provider). Read-only; not a stored column.
                  _created_at:
                    oneOf:
                    - type: string
                      format: date-time
                    - type: string
                    - type: object
                      properties: {}
                    description: The time the user was added to the workspace.
                  _updated_at:
                    oneOf:
                    - type: string
                      format: date-time
                    - type: string
                    - type: object
                      properties: {}
                    description: The time the user record was last updated.
                  last_active_at:
                    oneOf:
                    - type: string
                      format: date-time
                    - type: string
                    - type: object
                      properties: {}
                    nullable: true
                    description: The time the user was last active, derived from the later of their most recent sign-in or API key usage.
                required:
                - _id
                - name
                - roles
                - _created_at
                - _updated_at
                description: Field values keyed by field name; available fields depend on the object’s schema.
              relationships:
                type: object
                properties: {}
                description: Related resources keyed by relationship name, present when requested via `include`.
            required:
            - type
            - id
            - attributes
          description: The page of resources.
      required:
      - links
      - meta
      - data
    PublicUserResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - user
              description: The resource type; matches the `object` path parameter.
            id:
              type: string
              description: The unique ID of the resource.
            attributes:
              type: object
              properties:
                _id:
                  type: string
                  description: The unique ID of the user.
                name:
                  type: object
                  properties:
                    first_name:
                      type: string
                      description: The user’s first name.
                    last_name:
                      type: string
                      description: The user’s last name.
                    full_name:
                      type: string
                      description: The user’s full name (first and last combined).
                  required:
                  - first_name
                  - last_name
                  description: The user’s name.
                roles:
                  type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: string
                        enum:
                        - super_admin
                        - admin
                        - member
                      minItems: 1
                      maxItems: 1
                      description: The user’s role, as a single-element array.
                  required:
                  - items
                  description: The user’s workspace role, as a single-element array. Humans are `admin` or `member`; `super_admin` is reserved for the seeded system service account.
                email:
                  type: string
                  nullable: true
                  description: The user’s email address.
                profile_picture:
                  type: string
                  description: A URL to the user’s profile picture.
                is_service_account:
                  type: boolean
                  description: Server-derived. True for a non-human service account (an account with no identity provider). Read-only; not a stored column.
                _created_at:
                  oneOf:
                  - type: string
                    format: date-time
                  - type: string
                  - type: object
                    properties: {}
                  description: The time the user was added to the workspace.
                _updated_at:
                  oneOf:
                  - type: string
                    format: date-time
                  - type: string
                  - type: object
                    properties: {}
                  description: The time the user record was last updated.
                last_active_at:
                  oneOf:
                  - type: string
                    format: date-time
                  - type: string
                  - type: object
                    properties: {}
                  nullable: true
                  description: The time the user was last active, derived from the later of their most recent sign-in or API key usage.
              required:
              - _id
              - name
              - roles
              - _created_at
              - _updated_at
              description: Field values keyed by field name; available fields depend on the object’s schema.
            relationships:
              type: object
              properties: {}
              description: Related resources keyed by relationship name, present when requested via `include`.
          required:
          - type
          - id
          - attributes
          description: The resource.
      required:
      - data
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Send your key in the Authorization header as: `api-key <your-api-key>`.'
    bearer:
      type: http
      scheme: bearer
      description: 'User access token authentication for endpoints that act across workspaces. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'