openapi: 3.2.0
info:
  title: Outline Access Requests 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: Access Requests
  description: '`AccessRequests` represent a request by a user for access to a document

    they do not currently have permission to view. The request can be approved

    or dismissed by a user with permission to share the document.'
paths:
  /accessRequests.create:
    post:
      tags:
      - Access Requests
      summary: Create an access request
      description: Request access to a document. The request will be sent to users with permission to share the document for approval or dismissal.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
                  format: uuid
                  description: Identifier for the document to request access to.
              required:
              - documentId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AccessRequest'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/Validation'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: accessRequestsCreate
  /accessRequests.info:
    post:
      tags:
      - Access Requests
      summary: Retrieve an access request
      description: Retrieve information about an access request by `id`, or the current user's pending request for a document by `documentId`. At least one of these parameters must be provided.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for the access request.
                documentId:
                  type: string
                  format: uuid
                  description: Identifier for the document to find a pending request for the current user.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AccessRequest'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/Validation'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: accessRequestsInfo
  /accessRequests.approve:
    post:
      tags:
      - Access Requests
      summary: Approve an access request
      description: Approve a pending access request, granting the requesting user a membership on the document with the specified permission.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for the access request.
                permission:
                  type: string
                  description: The permission to grant the requesting user.
                  enum:
                  - read
                  - read_write
                  - admin
                  default: read
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AccessRequest'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/Validation'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: accessRequestsApprove
  /accessRequests.dismiss:
    post:
      tags:
      - Access Requests
      summary: Dismiss an access request
      description: Dismiss a pending access request without granting the requesting user access to the document.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Unique identifier for the access request.
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AccessRequest'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/Validation'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: accessRequestsDismiss
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'
    Validation:
      description: The request failed one or more validations.
      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
    AccessRequest:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object.
          readOnly: true
          format: uuid
        documentId:
          type: string
          description: Identifier for the document this request is for.
          format: uuid
        userId:
          type: string
          description: Identifier for the user that made the request.
          format: uuid
        user:
          $ref: '#/components/schemas/User'
        teamId:
          type: string
          description: Identifier for the workspace the request belongs to.
          format: uuid
        status:
          type: string
          description: The current status of the access request.
          enum:
          - pending
          - approved
          - dismissed
        responderId:
          type:
          - string
          - 'null'
          description: Identifier for the user that responded to the request, if any.
          format: uuid
        responder:
          $ref: '#/components/schemas/User'
        respondedAt:
          type:
          - string
          - 'null'
          description: The date and time the request was responded to, if any.
          format: date-time
        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
    Ability:
      description: A single permission granted by a policy
      example: true
      oneOf:
      - type: array
        items:
          type: string
      - type: boolean
    Policy:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object this policy references.
          format: uuid
          readOnly: true
        abilities:
          type: object
          description: The abilities that are allowed by this policy, if an array is returned then the individual ID's in the array represent the memberships that grant the ability.
          additionalProperties:
            $ref: '#/components/schemas/Ability'
          example:
            read: true
            update: true
            delete: false
    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
  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