openapi: 3.0.3
info:
  title: XBRL
  description: Endpoints to manage XBRL data.
  version: 1.0.0
  contact:
    email: rrplteam@workiva.com
    name: Workiva RRPL Team
servers:
  - url: https://api.app.wdesk.com
    description: US
  - url: https://api.eu.wdesk.com
    description: EU
  - url: https://api.apac.wdesk.com
    description: APAC
tags:
  - name: XBRL
    description: Endpoints related to XBRL entities and operations.
  - name: IAM
    description: |
      Before your application can access private data using other Workiva APIs, it must obtain an access token that grants access to those APIs.

      Use the IAM REST API endpoint to exchange your OAuth credentials (client_id and client_secret) for a token.
paths:
  /documents/{documentId}/xbrlProfiles:
    get:
      summary: Retrieve a list of XbrlProfiles by a Document ID
      description: |
        Returns a paginated list of [`XbrlProfiles`](ref:xbrl#xbrlprofile) using a [`Document`](ref:documents#document) ID.

        Responds with a bad request error for the following scenarios:
        - The `$filter` query parameter uses an unsupported filter.
        - The `$maxpagesize` query parameter is greater than 1000.
        - The `$next` query parameter corresponds to a non-existent page of results.
      operationId: getXbrlProfilesByDocumentId
      tags:
        - XBRL
      parameters:
        - $ref: '#/components/parameters/DocumentId'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/MaxPageSize'
        - $ref: '#/components/parameters/Next'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XbrlProfilesListResult'
              example:
                data:
                  - id: 9fb1c529-5ccb-48e1-8b19-de1431c3693e
                    label: Example Profile
                    archived: false
                '@nextLink': <opaque_url>
          headers: {}
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
      security:
        - oauth:
            - file:read
  /documents/{documentId}/xbrlProfiles/{xbrlProfileId}/sections/batchUpdate:
    post:
      summary: Batch update a list of SectionXbrlProperties by Section IDs
      description: |
        Batch updates a list of [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) using [`Section`](ref:documents#section) IDs and returns a list of the successfully
        updated [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties).

        ### Options

        | Path            | PATCH Operations Supported | Value Type |
        |-----------------|----------------------------|------------|
        | `/xbrlDisabled` | `replace`                  | `boolean`  |

        Responds with a bad request error for the following scenarios:
        - The `data` array is not provided or empty.
        - The `data` array contains duplicate section IDs.
        - The request contains more than 200 updates.
        - A `SectionXbrlPropertiesUpdate.patch` contains no operations, conflicting operations, or an unsupported operation.
      operationId: batchUpdateSectionXbrlPropertiesBySectionIds
      parameters:
        - $ref: '#/components/parameters/DocumentId'
        - $ref: '#/components/parameters/XbrlProfileId'
      tags:
        - XBRL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateSectionXbrlPropertiesRequest'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionXbrlPropertiesListResult'
              example:
                data:
                  - section: 257a1db8080749c6887338495b929248
                    xbrlDisabled: true
          headers: {}
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'
      security:
        - oauth:
            - file:write
  /oauth2/token:
    post:
      summary: Retrieve a token
      description: |
        Include the client_id and client_secret in the body of the request as form encoded parameters. For example, the body of the request would be `grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>`. The client can optionally specify a `scope` parameter to limit the scope of the returned [access token](ref:helpers#bearertoken). In turn, the server uses a `scope` response parameter to inform the client of the scope of the actual access token issued. The actual `scope` returned may not match the `scope` requested. Subsequent requests to Workiva APIs are authorized using the bearer token.
      operationId: tokenRequest
      security: []
      tags:
        - IAM
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                client_id:
                  description: A previously obtained client id.
                  type: string
                client_secret:
                  description: A previously obtained client secret.
                  type: string
                grant_type:
                  description: The grant type for the Bearer token. Must be client_credentials.
                  type: string
                  enum:
                    - client_credentials
                scope:
                  description: The scope of the access request.
                  type: string
              required:
                - grant_type
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BearerToken'
          description: OK
          headers: {}
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IamError'
          description: Bad Request
          headers: {}
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IamError'
          description: Unauthorized
          headers: {}
components:
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            file:read: Read files.
            file:write: Write files.
  parameters:
    DocumentId:
      description: The unique identifier of the document
      in: path
      name: documentId
      required: true
      schema:
        type: string
    Filter:
      description: The properties to filter the results by.
      in: query
      name: $filter
      required: false
      schema:
        type: string
    MaxPageSize:
      description: The maximum number of results to retrieve
      in: query
      name: $maxpagesize
      required: false
      schema:
        default: 1000
        maximum: 1000
        minimum: 1
        type: integer
    Next:
      description: Pagination cursor for next set of results.
      in: query
      name: $next
      required: false
      schema:
        example: JTI0bGltaXQ9MTAwJiUyNG9mZnNldD0xMDA
        type: string
    XbrlProfileId:
      description: The unique identifier of the XBRL profile
      in: path
      name: xbrlProfileId
      required: true
      schema:
        type: string
  headers: {}
  schemas:
    XbrlProfile:
      description: An XBRL Profile.
      type: object
      properties:
        id:
          description: The ID of the [`XbrlProfile`](ref:xbrl#xbrlprofile).
          type: string
          example: 9fb1c529-5ccb-48e1-8b19-de1431c3693e
        label:
          description: The label of the [`XbrlProfile`](ref:xbrl#xbrlprofile).
          type: string
          example: Example Profile
        archived:
          description: Whether the [`XbrlProfile`](ref:xbrl#xbrlprofile) is archived.
          type: boolean
          example: false
      required:
        - id
        - label
        - archived
    XbrlProfilesListResult:
      description: A resulting list of [`XbrlProfile`](ref:xbrl#xbrlprofile) resources.
      type: object
      properties:
        data:
          description: The [`XbrlProfile`](ref:xbrl#xbrlprofile) resources.
          type: array
          items:
            $ref: '#/components/schemas/XbrlProfile'
        '@nextLink':
          description: |
            Pagination link for the next set of [`XbrlProfile`](ref:xbrl#xbrlprofile) resources.
          type: string
          nullable: true
          example: <opaque_url>
      required:
        - data
    ErrorDetails:
      description: Additional details of the error
      properties:
        code:
          example: InvalidOrder
          type: string
        message:
          example: Ordering by 'name desc' is not supported
          type: string
        target:
          example: name
          type: string
      type: object
    ErrorResponse:
      description: Error response that indicates that the service is not able to process the incoming request. The reason is provided in the error message.
      properties:
        code:
          description: One of a server-defined set of error codes.
          example: BadArgument
          type: string
        details:
          items:
            $ref: '#/components/schemas/ErrorDetails'
          type: array
        documentationUrl:
          description: Link to some documentation relevant to the issue or endpoint in use.
          example: https://developers.workiva.com
          type: string
        message:
          description: A human-readable representation of the error.
          example: The provided $orderBy option is not supported.
          type: string
        target:
          description: The target of the error.
          example: $orderBy
          type: string
        version:
          description: The API version in use when the error occurred.
          example: "2026-01-01"
          type: string
      type: object
    JSONPatchOperation:
      description: |
        Represents a single JSON Patch operation. For more information, refer to the [PATCH Update documentation](ref:patch-updates).
      example:
        op: replace
        path: /name
        value: New name
      properties:
        from:
          type: string
        op:
          enum:
            - add
            - remove
            - replace
            - move
            - copy
            - test
          type: string
        path:
          type: string
        value:
          nullable: true
      required:
        - path
        - op
      type: object
    JSONPatchDocument:
      description: |
        Represents a collection of JSON patch operations. For more information, refer to the [PATCH Update documentation](ref:patch-updates).
      items:
        $ref: '#/components/schemas/JSONPatchOperation'
      type: array
    SectionXbrlPropertiesUpdate:
      description: An update for a [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) resource.
      type: object
      properties:
        section:
          description: The ID of the [`Section`](ref:documents#section), which corresponds to `SectionXbrlProperties.section`.
          type: string
          example: 257a1db8080749c6887338495b929248
        patch:
          description: The [JSON Patch document](https://datatracker.ietf.org/doc/html/rfc6902#section-3) to apply to the [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) resource.
          allOf:
            - $ref: '#/components/schemas/JSONPatchDocument'
          example:
            - op: replace
              path: /xbrlDisabled
              value: true
      required:
        - section
        - patch
    BatchUpdateSectionXbrlPropertiesRequest:
      description: A request to batch update multiple [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) resources.
      type: object
      properties:
        data:
          description: The updates for multiple [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) resources.
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/SectionXbrlPropertiesUpdate'
      required:
        - data
    SectionXbrlProperties:
      description: An entity that contains XBRL properties for a [`Section`](ref:documents#section).
      type: object
      properties:
        section:
          description: The ID of the [`Section`](ref:documents#section).
          type: string
          example: 257a1db8080749c6887338495b929248
        xbrlDisabled:
          description: Whether XBRL is disabled for the section.
          type: boolean
          example: true
      required:
        - section
        - xbrlDisabled
    SectionXbrlPropertiesListResult:
      description: A resulting list of [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) resources.
      type: object
      properties:
        data:
          description: The [`SectionXbrlProperties`](ref:xbrl#sectionxbrlproperties) resources.
          type: array
          items:
            $ref: '#/components/schemas/SectionXbrlProperties'
      required:
        - data
    BearerToken:
      description: |
        [Bearer token](ref:helpers#bearertoken) to use in subsequent requests to the Workiva APIs.
      properties:
        access_token:
          description: The opaque string used to authorize and make requests on behalf of the user
          type: string
        expires_in:
          description: The number of seconds the access token is valid
          type: integer
        scope:
          description: The limits of the user's access with the token, such as Read or Create
          type: string
        token_type:
          description: The type of access token; typically bearer
          type: string
      required:
        - access_token
        - expires_in
        - token_type
        - scope
      type: object
    IamError:
      description: Error response object containing an error code.
      properties:
        error:
          description: |
            The possible `error` codes are:
            - `invalid_request` - The request is missing a required parameter, includes an invalid parameter
              value, includes a parameter more than once, or is otherwise malformed.
            - `unauthorized_client` - The client is not authorized to request an authorization
              code using this method.
            - `access_denied` - The resource owner or authorization server denied the request.
            - `unsupported_response_type` - The authorization server does not support obtaining an authorization
              code using this method.
            - `invalid_scope` - The requested scope is invalid, unknown, or malformed.
            - `server_error` - The authorization server encountered an unexpected condition that prevented it
              from fulfilling the request.
            - `temporarily_unavailable` - The authorization server is currently unable to handle the request
              due to a temporary overloading or maintenance of the server.
          type: string
        error_description:
          description: Human-readable ASCII text providing additional information.
          type: string
        error_uri:
          description: |
            A URI identifying a human-readable web page with information about the error.
          type: string
      type: object
  responses:
    BadRequest:
      description: Bad Request
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BadRequest:
              value:
                code: 400BadRequest
                message: The request was unacceptable, often due to a missing or invalid parameter
    Unauthorized:
      description: Unauthorized
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Unauthorized:
              value:
                code: 401Unauthorized
                message: No valid API token provided
    Forbidden:
      description: Forbidden
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Forbidden:
              value:
                code: 403Forbidden
                message: The API token does not have permissions to perform the request
    NotFound:
      description: Not Found
      headers: {}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotFound:
              value:
                code: 404NotFound
                message: The requested resource could not be found
    TooManyRequests:
      description: Too Many Requests
      headers:
        Retry-After:
          description: The number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            TooManyRequests:
              value:
                code: 429TooManyRequests
                message: Too many requests have been made against the API in too short a time
