openapi: 3.2.0
info:
  title: Outline File Operations API
  description: '# Introduction


    The Outline API is structured in an RPC style.'
  version: 0.1.0
  contact:
    email: hello@getoutline.com
  license:
    name: BSD-3-Clause
    url: https://github.com/outline/openapi/blob/main/LICENSE
servers:
- url: https://app.getoutline.com/api
  description: Cloud hosted
- url: https://{domain}/api
  description: Self-hosted on your own server
  variables:
    domain:
      default: example.com
security:
- BearerAuth: []
- OAuth2:
  - read
  - write
tags:
- name: File Operations
  description: '`FileOperations` represent background jobs for importing or exporting files.

    You can query the file operation to find the state of progress and any

    resulting output.'
paths:
  /fileOperations.info:
    post:
      tags:
      - File Operations
      summary: Retrieve a file operation
      description: Retrieve the details and current status of a file operation by its unique identifier. File operations represent long-running import or export tasks.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the file operation.
                  format: uuid
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FileOperation'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: fileOperationsInfo
  /fileOperations.delete:
    post:
      tags:
      - File Operations
      summary: Delete a file operation
      description: Delete a file operation and its associated files. This is useful for cleaning up completed or failed import/export operations.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the file operation.
                  format: uuid
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: fileOperationsDelete
  /fileOperations.redirect:
    post:
      tags:
      - File Operations
      summary: Retrieve the file
      description: Load the resulting file from where it is stored based on the id. A temporary, signed url with embedded credentials is generated on demand.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the file operation.
                  format: uuid
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: fileOperationsRedirect
  /fileOperations.list:
    post:
      tags:
      - File Operations
      summary: List all file operations
      description: List all file operations for the current workspace, filtered by type (import or export).
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Pagination'
              - $ref: '#/components/schemas/Sorting'
              - type: object
                properties:
                  type:
                    type: string
                    description: The type of fileOperation
                    example: export
                    enum:
                    - export
                    - import
                required:
                - type
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileOperation'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: fileOperationsList
components:
  responses:
    RateLimited:
      description: The request was rate limited.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
                example: false
              error:
                type: string
                example: rate_limit_exceeded
              status:
                type: number
                example: 429
    Unauthorized:
      description: The current API key is not authorized to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthenticated:
      description: The API key is missing or otherwise invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    RateLimit-Remaining:
      schema:
        type: integer
      description: How many requests are left in the current duration.
    RateLimit-Reset:
      schema:
        type: string
      description: Timestamp in the future the duration will reset.
    RateLimit-Limit:
      schema:
        type: integer
      description: The maximum requests available in the current duration.
    Retry-After:
      schema:
        type: integer
      description: Seconds in the future to retry the request, if rate limited.
  schemas:
    UserRole:
      type: string
      enum:
      - admin
      - member
      - viewer
      - guest
    Error:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
        message:
          type: string
        status:
          type: number
        data:
          type: object
    Pagination:
      type: object
      properties:
        offset:
          type: number
          example: 0
        limit:
          type: number
          example: 25
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object.
          readOnly: true
          format: uuid
        name:
          type: string
          description: The name of this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
          example: Jane Doe
        avatarUrl:
          type: string
          format: uri
          description: The URL for the image associated with this user, it will be displayed in the application UI and email notifications.
        color:
          type: string
          description: A color representing the user, used in the UI for avatars without an image.
          readOnly: true
        email:
          type: string
          description: The email associated with this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
          format: email
          readOnly: true
        role:
          $ref: '#/components/schemas/UserRole'
        isSuspended:
          type: boolean
          description: Whether this user has been suspended.
          readOnly: true
        lastActiveAt:
          type:
          - string
          - 'null'
          description: The last time this user made an API request, this value is updated at most every 5 minutes.
          readOnly: true
          format: date-time
        timezone:
          type:
          - string
          - 'null'
          description: The timezone this user has registered.
        createdAt:
          type: string
          description: The date and time that this user first signed in or was invited as a guest.
          readOnly: true
          format: date-time
        updatedAt:
          type: string
          description: The date and time that this user was last updated.
          readOnly: true
          format: date-time
        deletedAt:
          type:
          - string
          - 'null'
          description: The date and time that this user was deleted, if applicable.
          readOnly: true
          format: date-time
    Sorting:
      type: object
      properties:
        sort:
          type: string
          example: updatedAt
        direction:
          type: string
          example: DESC
          enum:
          - ASC
          - DESC
    FileOperation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object.
          readOnly: true
          format: uuid
        type:
          type: string
          example: export
          description: The type of file operation.
          readOnly: true
          enum:
          - import
          - export
        format:
          type: string
          description: The file format of the resulting file.
          example: outline-markdown
          readOnly: true
        name:
          type: string
          description: The name of the file operation, derived from the collection name, document title, or file name.
          readOnly: true
        state:
          type: string
          description: The state of the file operation.
          example: complete
          readOnly: true
          enum:
          - creating
          - uploading
          - complete
          - error
          - expired
        error:
          type:
          - string
          - 'null'
          description: An error message if the file operation failed.
          readOnly: true
        size:
          type: string
          description: The size of the resulting file in bytes. Returned as a string as the value may exceed the safe integer range.
          readOnly: true
          example: '2048'
        collectionId:
          type:
          - string
          - 'null'
          description: Identifier for the associated collection, if the file operation is scoped to a single collection.
          readOnly: true
          format: uuid
        documentId:
          type:
          - string
          - 'null'
          description: Identifier for the associated document, if the file operation is scoped to a single document.
          readOnly: true
          format: uuid
        user:
          $ref: '#/components/schemas/User'
        createdAt:
          type: string
          description: The date and time that this object was created
          readOnly: true
          format: date-time
        updatedAt:
          type: string
          description: The date and time that this object was last changed
          readOnly: true
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.getoutline.com/oauth/authorize
          tokenUrl: https://app.getoutline.com/oauth/token
          refreshUrl: https://app.getoutline.com/oauth/token
          scopes:
            read: Read access
            write: Write access