Coda Project Organization Users API

openapi: 3.2.0
info:
  version: 0.0.2
  title: Superhuman Docs Admin Organization Users API
  license:
    name: Superhuman Developer Terms
    url: https://docs.superhuman.com/trust/developer
  description: '# Introduction


    The Superhuman Docs Admin API is a RESTful API that allows programmatic access to administrative reports & capabilities within Superhuman Docs (formerly Coda).'
  termsOfService: https://superhuman.com/legal/terms
  contact:
    name: Developer Support
    url: https://superhuman.com/developers
    email: care@superhuman.com
  x-logo:
    url: https://cdn.coda.io/icons/png/color/superhuman-docs-128.png
    backgroundColor: transparent
    altText: Superhuman Docs Admin API
    href: '#'
servers:
- url: https://docs.superhuman.com/apis/admin/v1
  description: Superhuman Docs Admin API (v1)
security:
- Bearer: []
tags:
- name: Organization Users
  description: This API enables viewing and modifying user information at the Organization level.
paths:
  /organizations/{organizationId}/users:
    get:
      summary: List organization users
      description: Returns a list of users within an organization, across all registered domains.
      operationId: listOrgUsers
      tags:
      - Organization Users
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/isActivated'
      - $ref: '#/components/parameters/query'
      - name: emails
        description: List of emails of users to retrieve.
        in: query
        required: false
        example:
        - april@example.com
        - june@example.com
        explode: false
        schema:
          type: array
          items:
            type: string
            format: email
      - name: deactivatedAfter
        in: query
        description: Return users deactivated at or after the given Unix timestamp.
        schema:
          type: number
      - name: includeOwnedDocCounts
        in: query
        description: Include the count of docs owned by each user.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: List of Superhuman Docs users matching the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgUserList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: 'import requests


          headers = {''Authorization'': ''Bearer <your API token>''}

          uri = ''https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users''

          res = requests.get(uri, headers=headers, params=params).json()


          print(f''First user is: {res["items"][0]["email"]}'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users' |\n  jq .items[0].email\n"
  /organizations/{organizationId}/users/transferResources:
    post:
      summary: Transfer user resources
      description: Transfers resources such as docs and workspace membership from a deactivated user to an active user.
      operationId: transferResources
      tags:
      - Organization Users
      parameters:
      - $ref: '#/components/parameters/organizationId'
      requestBody:
        description: Parameters for the resource transfer.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferResourcesRequest'
      responses:
        '202':
          description: Request accepted and being processed asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResourcesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: "import requests\n\nheaders = {'Authorization': 'Bearer <your API token>'}\nuri = 'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users/transferResources'\nbody = {\n  'fromUser': 'joe@example.com',\n  'toUser': 'april@example.com',\n}\nres = requests.get(uri, headers=headers, json=body).json()\n\nprint(f'Result: {res.status_code}')\n# => Result: 201\n"
  /organizations/{organizationId}/users/{userEmail}/activate:
    post:
      summary: Activate a user
      description: Activates a deactivated user.
      operationId: activateOrgUser
      tags:
      - Organization Users
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/userEmail'
      requestBody:
        description: Parameters for activating a deactivated user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgUserActivationChangeRequest'
      responses:
        '200':
          description: Response indicating the user activation request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgUserActivationChangeResult'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: 'import requests


          headers = {''Authorization'': ''Bearer <your API token>''}

          uri = ''https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users/<user email>/activate''

          res = requests.get(uri, headers=headers, params=params).json()


          print(f''Successully activated!'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users/<user email>/activate'\n"
  /organizations/{organizationId}/users/{userEmail}/deactivate:
    post:
      summary: Deactivate a user
      description: Deactivates a user, ensuring the user is no longer paid and allowing their docs to be reassigned to a new owner.
      operationId: deactivateOrgUser
      tags:
      - Organization Users
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/userEmail'
      requestBody:
        description: Parameters for deactivating a user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgUserActivationChangeRequest'
      responses:
        '200':
          description: Response indicating the user deactivation request was successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgUserActivationChangeResult'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: 'import requests


          headers = {''Authorization'': ''Bearer <your API token>''}

          uri = ''https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users/<user email>/deactivate''

          res = requests.get(uri, headers=headers, params=params).json()


          print(f''Successully deactivated!'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/users/<user email>/deactivate'\n"
components:
  parameters:
    query:
      name: query
      description: Search terms used to narrow down results.
      in: query
      required: false
      example: feature%parity
      schema:
        type: string
    isActivated:
      name: isActivated
      description: Filter results to users based on their activation status.
      in: query
      required: false
      schema:
        type: boolean
        x-no-default: true
    limit:
      name: limit
      description: Maximum number of results to return in this query.
      in: query
      example: 10
      schema:
        type: integer
        minimum: 1
        default: 100
        maximum: 500
    organizationId:
      name: organizationId
      description: ID of the organization.
      in: path
      required: true
      example: org-AbCDeFGHIj
      schema:
        type: string
    pageToken:
      name: pageToken
      description: An opaque token used to fetch the next page of results.
      in: query
      example: eyJsaW1pd
      schema:
        type: string
    userEmail:
      name: userEmail
      description: User to act upon.
      in: path
      required: true
      example: april@example.com
      schema:
        type: string
        format: email
  responses:
    TooManyRequestsError:
      description: The client has sent too many requests.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 429
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Too Many Requests
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Too Many Requests
    NotFoundError:
      description: The resource could not be located with the current API token.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 404
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Not Found
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Not Found
    UnauthorizedError:
      description: The API token is invalid or has expired.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 401
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Unauthorized
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Unauthorized
    ForbiddenError:
      description: The API token does not grant access to this resource.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 403
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Forbidden
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Forbidden
    BadRequestError:
      description: The request parameters did not conform to expectations.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 400
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Bad Request
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Bad Request
  schemas:
    OrgUser:
      x-schema-name: OrgUser
      description: Metadata of a user in an organization.
      type: object
      required:
      - email
      - name
      - status
      - registeredAt
      additionalProperties: false
      properties:
        id:
          type: number
          description: Unique id of the user.
          example: 12345
        email:
          type: string
          description: Email of the user.
          example: hello@example.com
        name:
          type: string
          description: Name of the user.
          example: Sally Jane
        pictureUrl:
          type: string
          description: Picture url of the user.
          format: url
          example: codahosted.io/123
        status:
          $ref: '#/components/schemas/OrgUserStatus'
        registeredAt:
          type: string
          format: date-time
          description: Timestamp representing when the user registered with Superhuman Docs.
          example: '2018-04-11T00:18:57.946Z'
        deactivatedAt:
          type: string
          format: date-time
          description: Timestamp representing when the user was deactivated from Superhuman Docs.
          example: '2018-04-11T00:18:57.946Z'
        ownedDocCount:
          type: number
          description: Number of docs owned by this user.
          example: 12
    TransferResourcesResponse:
      x-schema-name: TransferResourcesResponse
      description: Result of the transfer resources request
      type: object
      required:
      - requestId
      additionalProperties: false
      properties:
        requestId:
          type: string
          description: An opaque identifier that represents the request.
          example: c5cb3278-800e-4ae3-be53-19b0b794f8e1
    NextPageToken:
      description: If specified, an opaque token used to fetch the next page of results.
      type: string
      example: eyJsaW1pd
    OrgUserList:
      x-schema-name: OrgUserList
      type: object
      required:
      - items
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrgUser'
        href:
          type: string
          format: url
          description: API link to these results
          example: https://docs.superhuman.com/apis/admin/v1/organizations/org-1AbcdeFgh1/users?limit=20
        nextPageToken:
          $ref: '#/components/schemas/NextPageToken'
        nextPageLink:
          allOf:
          - $ref: '#/components/schemas/NextPageLink'
          - type: string
            example: https://docs.superhuman.com/apis/admin/v1/organizations/org-1AbcdeFgh1/users?pageToken=eyJsaW1pd
    OrgUserActivationChangeRequest:
      x-schema-name: OrgUserActivationChangeRequest
      description: Payload for making changes to an org user's state.
      type: object
      additionalProperties: false
      properties:
        bypassScim:
          type: boolean
          description: By default, requests to update org users' activation state are rejected if SCIM is enabled for the organization. Updating membership here may cause Superhuman Docs to be out of sync with your identity provider and/or refreshes from SCIM may overwrite your changes here. Set this flag to bypass this protection.
    OrgUserActivationChangeResult:
      x-schema-name: OrgUserActivationChangeResult
      description: The result of a change to an org user's state.
      type: object
      additionalProperties: false
      properties: {}
    OrgUserStatus:
      x-schema-name: OrgUserStatus
      type: string
      enum:
      - Active
      - Deactivated
      - Deleted
      x-tsEnumNames:
      - Active
      - Deactivated
      - Deleted
    NextPageLink:
      description: If specified, a link that can be used to fetch the next page of results.
      type: string
      format: url
    TransferResourcesRequest:
      x-schema-name: TransferResourcesRequest
      description: Payload for transferring resources between users.
      type: object
      required:
      - fromEmail
      - toEmail
      additionalProperties: false
      properties:
        fromEmail:
          type: string
          description: The email address of the user to transfer resources away from.
          example: joe@example.com
        toEmail:
          type: string
          description: The email address of the user to transfer resources to.
          example: april@example.com
        filterDocIds:
          type: array
          description: List of IDs of docs to transfer. Must be owned by the from user. If unspecified transfers all docs the from user owns.
          example:
          - AbCDeFGH
          items:
            type: string
  securitySchemes:
    Bearer:
      description: 'The Superhuman Docs Admin API can be accessed using an API token, which can be obtained from [*My account*](https://docs.superhuman.com/account)

        in Superhuman Docs. This token should be specified by setting a header as follows.


        ```Authorization: Bearer <api_token>```


        Keep your token safe, as anyone who gets access to it can access your account. Once a token is created

        it cannot be viewed or modified, so don''t lose it.

        '
      type: http
      scheme: bearer
      bearerFormat: UUID
x-tagGroups:
- name: API Tokens
  tags:
  - API Tokens
- name: Docs
  tags:
  - Docs
  - Doc Permissions
  - Doc Export
- name: Doc Structure
  tags:
  - Pages
- name: Events
  tags:
  - Events
- name: Folders
  tags:
  - Folders
  - Folder Permissions
- name: Groups
  tags:
  - Groups
- name: Import
  tags:
  - Preferences
- name: LegalHolds
  tags:
  - LegalHolds
- name: Organizations
  tags:
  - Organizations
  - Organization Users
  - Pack Controls
  - Pack Configurations
- name: Packs
  tags:
  - Packs
- name: Webhooks
  tags:
  - Webhooks
- name: Workspaces
  tags:
  - Workspaces
  - Workspace Users