Nooks Introspection API

openapi: 3.2.0
info:
  title: Nooks Sequencing Introspection API
  version: 0.1.0
  description: The Nooks Sequencing API provides programmatic access to manage sequences, tasks, templates, and prospect engagement workflows created using the Nooks SEP.
  contact:
    name: Nooks API Support
    email: support@nooks.in
    url: https://www.nooks.in
  license:
    name: Proprietary
  x-logo:
    url: ./nooks-logo.svg
    altText: Nooks Logo
    href: https://www.nooks.ai
servers:
- url: https://partner-api.nooks.in/v1
  description: Production API
security:
- BearerAuth: []
tags:
- name: Introspection
  description: Inspect the authenticated principal
paths:
  /me:
    get:
      operationId: getMe
      summary: Get the authenticated principal
      description: 'Returns the workspace and user for the current credential. A `200`

        confirms the credential is valid; `401` means it''s expired,

        revoked, or malformed.


        - For OAuth callers, `userId` is the end user who authorized the

        token (JWT `sub`).

        - For API-key callers, `userId` is the Nooks user who generated

        the key in **Developer Settings → API Keys**.

        - `userId` is always populated. `email` and `name` are `null` if

        that user no longer has a seat in the workspace.

        - `clientId` and `scopes` are `null` for API-key callers (API

        keys have full workspace access).


        Response is intentionally flat as an introspection endpoint and

        doesn''t follow the nested ReferenceObject shape the resource

        endpoints use.


        Available to any authenticated caller regardless of granted

        scopes.


        Example:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/me'' \

        -H "Authorization: Bearer "

        ```'
      tags:
      - Introspection
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - workspaceId
                - userId
                - email
                - name
                - authType
                - clientId
                - scopes
                properties:
                  workspaceId:
                    type: string
                    description: Workspace the credential is scoped to.
                  userId:
                    type: string
                    description: 'Acting user''s ID. For OAuth this is the end user

                      who authorized the token (JWT `sub`); for API keys

                      it''s the user who created the key. Always populated.

                      '
                  email:
                    type: string
                    format: email
                    nullable: true
                    description: Email of the acting user; `null` if no longer a seat holder.
                  name:
                    type: string
                    nullable: true
                    description: Full name of the acting user; `null` if no longer a seat holder.
                  authType:
                    type: string
                    enum:
                    - oauth
                    - apiKey
                    description: Authentication scheme used for the request.
                  clientId:
                    type: string
                    nullable: true
                    description: 'For OAuth: the partner-facing client identifier

                      (the same `client_id` used in OAuth requests). For

                      API keys: `null`.

                      '
                  scopes:
                    type: array
                    nullable: true
                    items:
                      type: string
                    description: 'For OAuth: the granted scope list from the access

                      token. For API keys: `null` (keys grant blanket

                      access).

                      '
              examples:
                oauth:
                  summary: OAuth caller
                  value:
                    workspaceId: example-workspace
                    userId: KKLvN5wQoghWFwUvC75CZ12QM7I3
                    email: jane@example.com
                    name: Jane Doe
                    authType: oauth
                    clientId: acme-integration
                    scopes:
                    - sequences:read
                    - prospects:read
                apiKey:
                  summary: API-key caller
                  value:
                    workspaceId: example-workspace
                    userId: 1erKK6gEL7ZUDFPEjCiHfV02fFD3
                    email: john@example.com
                    name: John Smith
                    authType: apiKey
                    clientId: null
                    scopes: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Error:
      type: object
      description: Standard error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: NOT_FOUND
            message:
              type: string
              description: Human-readable error message
              example: The requested resource was not found
        traceId:
          type: string
          description: 'Request trace identifier for correlating this error with server

            logs and support requests. Present whenever the request carried a

            trace context (the normal case); omitted otherwise.

            '
          example: abc123def456
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token sent in the `Authorization` header. Accepts either a

        long-lived Nooks API key (`nooks-api-...`, from Developer Settings →

        API Keys) or an OAuth 2.0 access token issued by

        `https://oauth.nooks.in`. Use whichever you already have — the API

        validates both formats on the same header. For full OAuth flow

        details (authorize/token endpoints, scopes, refresh behavior) see

        the Authentication section of this spec''s introduction.

        '
x-tagGroups:
- name: API Reference
  tags:
  - Sequences
  - SequenceSteps
  - Emails
  - Users
  - SequenceStates
  - Prospects
  - Accounts
  - Notes
  - Mailboxes
  - Calls
  - CallDispositions
  - Tasks
  - EmailTemplates
  - Introspection