openapi: 3.1.0
info:
  title: API Reference subpackage_bulkSync subpackage_organization API
  version: 1.0.0
servers:
- url: https://app.polytomic.com
tags:
- name: subpackage_organization
paths:
  /api/organization:
    get:
      operationId: get-current
      summary: Get Current Organization
      description: 'Returns the organization the caller is authenticated against.


        This endpoint is the safest way to discover the effective organization for a

        user-scoped or organization-scoped credential. It does not let callers inspect

        arbitrary organizations; it only returns the organization implied by the

        credential that authenticated the request.


        If you need to enumerate or look up organizations across a partner account, use

        [`GET /api/organizations`](../../api-reference/organization/list) or

        [`GET /api/organizations/{id}`](../../api-reference/organization/get) instead.'
      tags:
      - subpackage_organization
      parameters:
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/organizations:
    get:
      operationId: list
      summary: Get Organizations
      description: 'Lists every organization accessible to the calling partner, with the partner''s owner organization first.


        In `2025-09-18`, this endpoint is partner-scoped rather than a general

        "current caller visibility" listing. The partner owner organization is returned

        first, followed by child organizations.


        This ordering matters for partner workflows such as shared connections, where

        the parent connection must live in the partner owner organization.


        If you need only the organization implied by the current credential, use

        [`GET /api/organization`](../../api-reference/organization/get-current) instead.'
      tags:
      - subpackage_organization
      parameters:
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsEnvelope'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      operationId: create
      summary: Create Organization
      description: 'Creates a new organization under the calling partner account, optionally configuring SSO or OIDC at creation time.


        > 🚧 Requires partner key

        >

        > This endpoint is only accessible using [partner keys](../../guides/obtaining-api-keys#partner-keys).


        SSO and OIDC settings supplied at creation time can be updated later via

        `PUT /api/organizations/{id}`.'
      tags:
      - subpackage_organization
      parameters:
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationEnvelope'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRequestSchema'
  /api/organizations/{id}:
    get:
      operationId: get
      summary: Get Organization
      description: 'Returns a single organization by ID.


        > 📘 Credential scope varies by endpoint and API version

        >

        > Organization endpoints do not all share the same credential requirements.

        > Check each endpoint''s description for the caller scope that applies in that

        > API version.'
      tags:
      - subpackage_organization
      parameters:
      - name: id
        in: path
        description: Unique identifier of the organization.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      operationId: update
      summary: Update Organization
      description: 'Updates an organization''s name and SSO or OIDC configuration.


        > 🚧 Requires partner key

        >

        > This endpoint is only accessible using [partner keys](../../../guides/obtaining-api-keys#partner-keys).


        > 📘 SSO and OIDC configuration is replaced in full on each update. Include all

        > desired settings in the request body, not just the fields you want to change.'
      tags:
      - subpackage_organization
      parameters:
      - name: id
        in: path
        description: Unique identifier of the organization to update.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationRequestSchema'
    delete:
      operationId: delete
      summary: Delete Organization
      description: 'Deletes an organization.


        Partner callers cannot delete their own owner organization.'
      tags:
      - subpackage_organization
      parameters:
      - name: id
        in: path
        description: Unique identifier of the organization.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    UpdateOrganizationRequestSchema:
      type: object
      properties:
        client_id:
          type: string
          description: OIDC client ID issued by the identity provider.
        client_secret:
          type: string
          description: OIDC client secret issued by the identity provider. Write-only; never returned in responses.
        issuer:
          type: string
          description: OIDC issuer URL for organizations using OpenID Connect single sign-on.
        name:
          type: string
          description: Human-readable name of the organization. Must be unique across the partner account.
        sso_domain:
          type: string
          description: Email domain used to match users to this organization during SSO sign-in.
        sso_org_id:
          type: string
          description: WorkOS organization identifier linking this organization to its SAML/SSO configuration.
      required:
      - name
      title: UpdateOrganizationRequestSchema
    Organization:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the organization.
        issuer:
          type: string
          description: OIDC issuer URL for organizations using OpenID Connect single sign-on.
        name:
          type: string
          description: Human-readable name of the organization.
        sso_domain:
          type: string
          description: Email domain used to match users to this organization during SSO sign-in.
        sso_org_id:
          type: string
          description: WorkOS organization identifier linking this organization to its SAML/SSO configuration.
      title: Organization
    CreateOrganizationRequestSchema:
      type: object
      properties:
        client_id:
          type: string
          description: OIDC client ID issued by the identity provider.
        client_secret:
          type: string
          description: OIDC client secret issued by the identity provider. Write-only; never returned in responses.
        issuer:
          type: string
          description: OIDC issuer URL for organizations using OpenID Connect single sign-on.
        name:
          type: string
          description: Human-readable name of the organization. Must be unique across the partner account.
        sso_domain:
          type: string
          description: Email domain used to match users to this organization during SSO sign-in.
        sso_org_id:
          type: string
          description: WorkOS organization identifier linking this organization to its SAML/SSO configuration.
      required:
      - name
      title: CreateOrganizationRequestSchema
    OrganizationsEnvelope:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Organization'
      title: OrganizationsEnvelope
    ApiError:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
        metadata:
          type: object
          additionalProperties:
            description: Any type
        status:
          type: integer
      title: ApiError
    OrganizationEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Organization'
      title: OrganizationEnvelope
  securitySchemes:
    bearerUserAPIKey:
      type: http
      scheme: bearer
      description: Bearer user API key
    orgScopedAPIKey:
      type: http
      scheme: basic
      description: Basic organization-scoped API key
    bearerPartnerKey:
      type: http
      scheme: bearer
      description: Bearer partner API key