Clarifymedical Object Access API

openapi: 3.2.0
info:
  title: Clarify Object Access API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
- bearer: []
tags:
- name: ObjectAccess
paths:
  /workspaces/{workspace}/objects/{object}/access:
    get:
      description: Returns entity-wide access delegations for the object type as a JSON:API collection. Entity-wide access delegation grants another user the same access you have to every record of that object type. The response includes both delegations you have granted and delegations granted to you. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: getObjectAccess
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: object
        required: true
        in: path
        description: 'The object type this delegation applies to: `meeting` or `message`.'
        schema:
          type: string
          enum:
          - meeting
          - message
      responses:
        '200':
          description: The access delegations you granted and those granted to you.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectAccessListResponse'
              example:
                data:
                - type: object-access
                  id: a1f4e6d2-8c9b-4f3a-9d5e-1b6c8a2f7d90
                  attributes:
                    _id: a1f4e6d2-8c9b-4f3a-9d5e-1b6c8a2f7d90
                    owner_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    delegate_id: 2b6e4f8a-3d1c-4a9e-8b5f-7c2a9d0e4f63
                    entity: meeting
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
      summary: List object access delegations
      tags:
      - ObjectAccess
    post:
      description: 'Grants another user entity-wide access delegation: the same access you have to every record of the given object type. Requires a paid plan with access delegation enabled. Requires a user-backed API key; workspace-actor API keys are not supported.'
      operationId: giveObjectAccess
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: object
        required: true
        in: path
        description: 'The object type this delegation applies to: `meeting` or `message`.'
        schema:
          type: string
          enum:
          - meeting
          - message
      - 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/CreateObjectAccessRequestDto'
            examples:
              grantAccess:
                summary: Grant access to a teammate
                value:
                  data:
                    type: object-access
                    attributes:
                      delegate_id: 2b6e4f8a-3d1c-4a9e-8b5f-7c2a9d0e4f63
      responses:
        '201':
          description: The created access delegation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectAccessResponse'
              example:
                data:
                  type: object-access
                  id: a1f4e6d2-8c9b-4f3a-9d5e-1b6c8a2f7d90
                  attributes:
                    _id: a1f4e6d2-8c9b-4f3a-9d5e-1b6c8a2f7d90
                    owner_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    delegate_id: 2b6e4f8a-3d1c-4a9e-8b5f-7c2a9d0e4f63
                    entity: meeting
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
      summary: Grant object access
      tags:
      - ObjectAccess
  /workspaces/{workspace}/objects/{object}/access/{id}:
    delete:
      description: Revokes a previously granted access delegation. Requires a paid plan with access delegation enabled. Returns 202 Accepted with an empty body. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: revokeObjectAccess
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: object
        required: true
        in: path
        description: 'The object type this delegation applies to: `meeting` or `message`.'
        schema:
          type: string
          enum:
          - meeting
          - message
      - name: id
        required: true
        in: path
        description: The unique ID of the access delegation.
        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:
        '202':
          description: The delegation was revoked. The response body is empty.
          content:
            application/json:
              example: {}
      summary: Revoke object access
      tags:
      - ObjectAccess
components:
  schemas:
    ObjectAccessListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - object-access
              id:
                type: string
              attributes:
                type: object
                properties:
                  _id:
                    type: string
                    description: The unique ID of the access delegation.
                  owner_id:
                    type: string
                    description: The ID of the user who granted access.
                  delegate_id:
                    type: string
                    description: The ID of the user who receives access.
                  entity:
                    type: string
                    enum:
                    - meeting
                    - message
                    description: The object type this delegation applies to.
                  _created_at:
                    type: string
                    format: date-time
                    description: When the delegation was created.
                  _created_by:
                    type: string
                    nullable: true
                    description: The ID of the user who created the delegation, or null if unknown.
                  _updated_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the delegation was last updated, or null if it has never been updated.
                  _updated_by:
                    type: string
                    nullable: true
                    description: The ID of the user who last updated the delegation, or null if it has never been updated.
                required:
                - _id
                - owner_id
                - delegate_id
                - entity
                - _created_at
                - _created_by
                - _updated_at
                - _updated_by
            required:
            - type
            - id
            - attributes
      required:
      - data
    ObjectAccessResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - object-access
              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 access delegation.
                owner_id:
                  type: string
                  description: The ID of the user who granted access.
                delegate_id:
                  type: string
                  description: The ID of the user who receives access.
                entity:
                  type: string
                  enum:
                  - meeting
                  - message
                  description: The object type this delegation applies to.
                _created_at:
                  type: string
                  format: date-time
                  description: When the delegation was created.
                _created_by:
                  type: string
                  nullable: true
                  description: The ID of the user who created the delegation, or null if unknown.
                _updated_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: When the delegation was last updated, or null if it has never been updated.
                _updated_by:
                  type: string
                  nullable: true
                  description: The ID of the user who last updated the delegation, or null if it has never been updated.
              required:
              - _id
              - owner_id
              - delegate_id
              - entity
              - _created_at
              - _created_by
              - _updated_at
              - _updated_by
              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
    CreateObjectAccessRequestDto:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - object-access
            attributes:
              description: Field values keyed by field name; available fields depend on the object’s schema. System fields (prefixed with a single `_`) cannot be set.
              type: object
              properties:
                delegate_id:
                  type: string
                  description: The ID of the user to grant access to.
              required:
              - delegate_id
              additionalProperties: true
          required:
          - type
          - attributes
          additionalProperties: false
          description: The resource to create.
      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. Every endpoint accepts it, and endpoints that act as a person accept only it. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'