Ocrolus Book Commands API

openapi: 3.0.0
info:
  title: Account Level Webhooks Book Commands API
  version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Book Commands
paths:
  /v1/book/add:
    post:
      summary: Create Book
      description: Create a <<glossary:Book>> that you can use to group related <<glossary:Document>>s. Each document must be uploaded to a <<glossary:Book>>, so you'll need to create one with this endpoint before you can upload files. <<glossary:Book>>s are generally used to store related <<glossary:Document>>s, such as for a loan application or a case file.
      operationId: create-a-book
      tags:
      - Book Commands
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the <<glossary:Book>> that will be created.
                book_class:
                  type: string
                  description: 'The processing type of the book. Can be either ''COMPLETE'' or ''INSTANT''.

                    By default this value will be set to `COMPLETE` unless your organization is configured to have `INSTANT` as the default.'
                  enum:
                  - COMPLETE
                  - INSTANT
                  - INSTANT_CLASSIFY_ONLY
                  - INSTANT_CLASSIFY_ISO_CAPTURE
                book_type:
                  type: string
                  description: Describes how the <<glossary:Book>> was created. This feature is in beta. See our guides on [OPTIMA](https://docs.ocrolus.com/docs/ocrolus-lab) and [WIDGET](https://docs.ocrolus.com/docs/widget) for additional information.
                  enum:
                  - DEFAULT
                  - OPTIMA
                  - WIDGET
                is_public:
                  type: boolean
                  description: '`true` allows all users in your organization to see and upload <<glossary:Document>>s into this <<glossary:Book>>.'
                xid:
                  type: string
                  description: A free form field that can be used to associate a <<glossary:Book>> with some identity outside of Ocrolus.
            example:
              name: Example Book
              is_public: true
              xid: 123ABC
              book_type: DEFAULT
              book_class: COMPLETE
      x-readme:
        samples-languages:
        - curl
        - python
        explorer-enabled: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: Success
                type: object
                properties:
                  status:
                    type: integer
                    description: A numerical code that indicates the status of the request.
                    example: 200
                  response:
                    type: object
                    description: An object received from the server that potentially contains data.
                    properties:
                      name:
                        type: string
                        description: The name of the <<glossary:Book>> that will be created.
                        example: Test Book
                      created:
                        example: '2022-11-11T10:03:06Z'
                        description: A timestamp of when the <<glossary:Book>> was created.
                        type: string
                      created_ts:
                        example: '2022-11-11T10:03:06Z'
                        description: A timestamp of when the <<glossary:Book>> was created.
                        type: string
                      pk:
                        example: 10399
                        description: The unique primary key of the <<glossary:Book>>
                        type: integer
                      owner_email:
                        example: email@address.com
                        description: The email of the user that created or currently owns the <<glossary:Book>>.
                        type: string
                      is_public:
                        type: boolean
                        description: Indicates if all users in your organization can see and upload <<glossary:Document>>s into this <<glossary:Book>>."
                        example: false
                        default: true
                      uuid:
                        example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
                        description: The unique identifier of the <<glossary:Book>>.
                        type: string
                      book_type:
                        type: string
                        description: Determines what type of processing the <<glossary:Book>> will go through. Options include DEFAULT, OPTIMA, or WIDGET.
                        example: DEFAULT
                      xid:
                        type: string
                        description: A free form field that can be used to associate a <<glossary:Book>> with some identity outside of Ocrolus.
                        example: ABC123
                      id:
                        type: integer
                        description: The <<glossary:PK>> of the <<glossary:Book>>.
                        example: 10399
                      book_class:
                        type: string
                        description: The processing type of the book. Can be one of 'COMPLETE', 'INSTANT', or 'QUALIFY'.
                  message:
                    type: string
                    default: OK
                    description: A textual description that indicates details about this response's status.
                    example: OK
              examples:
                Success:
                  value:
                    status: 200
                    response:
                      name: Example Book
                      created: '2023-05-25T17:23:45Z'
                      created_ts: '2023-05-25T17:23:45Z'
                      pk: 34101490
                      owner_email: email@address.com
                      is_public: true
                      uuid: 52dfdb53-6652-4d3a-a3db-fe864c6ff2fb
                      book_type: DEFAULT
                      xid: null
                      id: 34101490
                      book_class: COMPLETE
                    message: OK
        '400':
          description: Client Errors
          content:
            application/json:
              examples:
                Book already exists:
                  value:
                    status: 400
                    message: Book exists
                    code: 1402
                    meta:
                      status: 400
                      msg: Book exists
                      code: 1402
                    response: null
                No permission:
                  value:
                    status: 400
                    message: No permission to create new books
                    code: 2111
                    meta:
                      status: 400
                      msg: No permission to create new books
                      code: 2111
                    response: null
              schema:
                oneOf:
                - title: Book already exists
                  type: object
                  properties:
                    status:
                      type: integer
                      description: A numerical code that indicates the status of the request.
                      example: 400
                    message:
                      type: string
                      description: A textual description that indicates details about this response's status.
                      example: Book exists
                    code:
                      type: integer
                      description: A numerical code that indicates the nature of an error.
                      example: 1402
                      default: 0
                    meta:
                      type: object
                      description: An object received from the server that potentially contains information about the request.
                      properties:
                        status:
                          type: integer
                          description: A numerical code that indicates the status of the request.
                          example: 400
                          default: 0
                        msg:
                          type: string
                          description: A textual description that indicates details about this response's status.
                          example: Book exists
                        code:
                          type: integer
                          description: A numerical code that indicates the nature of an error.
                          example: 1401
                    response:
                      type: object
                      example: null
                      description: An object received from the server that potentially contains data.
  /v1/book/remove:
    post:
      summary: Delete Book
      description: 'Delete a <<glossary:Book>> that you no longer need.


        ---

        > 🚧 No turning back!

        > Deleting a <<glossary:Book>> also deletes the <<glossary:Document>>s contained within. This action is not reversible, meaning that you can''t recover deleted <<glossary:Document>>s and <<glossary:Book>>s. Make sure you''re ready!'
      operationId: delete-a-book
      tags:
      - Book Commands
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                book_id:
                  type: string
                  description: The <<glossary:PK>> of the <<glossary:Book>> you'd like to delete. Mutually exclusive with `book_uuid`.
                book_uuid:
                  type: string
                  description: 'The unique identifier of the <<glossary:Book>> you''d like to delete. Mutually exclusive with `book_id`. '
            example:
              book_uuid: 19aab921-25a5-4beb-a59e-ac72320061d6
              book_id: '30219565'
      x-readme:
        samples-languages:
        - curl
        - python
        explorer-enabled: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: Success
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                    description: A numerical code that indicates the status of the request.
                  message:
                    type: string
                    example: OK
                    description: A textual description that indicates details about this response's status.
                  response:
                    type: object
                    description: An object received from the server that potentially contains data.
                    example: null
              examples:
                Success:
                  value:
                    status: 200
                    message: OK
                    response: {}
        '400':
          description: Client Errors
          content:
            application/json:
              examples:
                Book not found:
                  value:
                    status: 400
                    code: 1401
                    response: null
                    message: Book not found
                    meta:
                      status: 400
                      msg: Book not found
                      code: 1401
                Missing Required Parameters:
                  value:
                    status: 400
                    code: 1103
                    response: null
                    message: Required pk or book uuid
                    meta:
                      status: 400
                      msg: Required pk or book uuid
                      code: 1103
                No Permission:
                  value:
                    status: 400
                    code: 2102
                    response: null
                    message: No permission to access this book
                    meta:
                      status: 400
                      msg: No permission to access this book
                      code: 2102
              schema:
                properties:
                  status:
                    type: integer
                    description: A numerical code that indicates the status of the request.
                    example: 400
                  code:
                    type: integer
                    description: A numerical code that indicates the nature of an error.
                    example: 1401
                  response:
                    type: object
                    description: An object received from the server that potentially contains data.
                  message:
                    type: string
                    description: A textual description that indicates details about this response's status.
                    example: Book not found
                  meta:
                    type: object
                    description: An object received from the server that potentially contains data.
                    properties:
                      status:
                        type: integer
                        example: 400
                        description: A numerical code that indicates the status of the request.
                      message:
                        type: string
                        example: Book not found
                        description: A textual description that indicates details about this response's status.
                      code:
                        type: integer
                        example: 1401
                        description: A numerical code that indicates the nature of an error.
  /v1/book/update:
    post:
      summary: Update Book
      description: Configure various properties of a <<glossary:Book>>.
      operationId: update-book
      tags:
      - Book Commands
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                book_uuid:
                  type: string
                  description: The unique identifier of the <<glossary:Book>> you want to configure. Mutually exclusive with `pk`.
                pk:
                  type: string
                  description: The <<glossary:PK>> of the <<glossary:Book>> you want to configure. Mutually exclusive with `book_uuid`.
                book_class:
                  type: string
                  description: Determines what type of processing the <<glossary:Book>> will go through. By default this value will be set to `COMPLETE` unless your organization is configured to have `INSTANT` as the default.
                  enum:
                  - COMPLETE
                  - INSTANT
                book_type:
                  type: string
                  description: Describes how the <<glossary:Book>> was created. This feature is in beta. See our guides on [OPTIMA](https://docs.ocrolus.com/docs/ocrolus-lab) and [WIDGET](https://docs.ocrolus.com/docs/widget) for additional information.
                  enum:
                  - DEFAULT
                  - OPTIMA
                  - WIDGET
                is_public:
                  type: boolean
                  description: '`true` allows all users in your organization to see and upload <<glossary:Document>>s into this <<glossary:Book>>.'
                name:
                  type: string
                  description: The <<glossary:Book>>'s new name. If not given, the name will be unchanged.
                xid:
                  type: string
                  description: A free form field that can be used to associate a <<glossary:Book>> with some identity outside of Ocrolus.
            example:
              book_uuid: 19aab921-25a5-4beb-a59e-ac72320061d6
              pk: 30219565
              name: Example Book
              is_public: true
              xid: 123ABC
              book_class: COMPLETE
              book_type: DEFAULT
      x-readme:
        samples-languages:
        - curl
        - python
        explorer-enabled: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: Success
                type: object
                properties:
                  status:
                    type: integer
                    description: A numerical code that indicates the status of the request.
                    example: 200
                    default: 0
                  response:
                    type: object
                    description: An object received from the server that potentially contains data.
                    properties:
                      name:
                        type: string
                        description: The name of the <<glossary:Book>>.
                        example: Test Book
                      created:
                        type: string
                        description: A timestamp of when the <<glossary:Book>> was created.
                        example: '2022-08-15T10:03:06Z'
                      created_ts:
                        type: string
                        description: A timestamp of when the <<glossary:Book>> was created.
                        example: '2022-08-15T10:03:06Z'
                      pk:
                        type: integer
                        description: The unique primary key of the <<glossary:Book>>
                        example: 10399
                      uuid:
                        type: string
                        description: The unique identifier of the <<glossary:Book>>.
                        example: 8dc88eed-2b6f-414a-82f2-a99bd181cf6e
                      owner_email:
                        type: string
                        description: The email of the user that created or currently owns the <<glossary:Book>>.
                        example: email@address.com
                      is_public:
                        type: boolean
                        description: Indicates if all users in your organization can see and upload <<glossary:Document>>s into this <<glossary:Book>>."
                        example: false
                        default: true
                      xid:
                        type: string
                        description: A free form field that can be used to associate a <<glossary:Book>> with some identity outside of Ocrolus.
                        example: ABC123
                      book_type:
                        type: string
                        description: Determines what type of processing the <<glossary:Book>> will go through. Options include DEFAULT, OPTIMA, or WIDGET.
                        example: DEFAULT
                      id:
                        type: integer
                        description: The <<glossary:PK>> of the <<glossary:Book>>
                        example: 10399
                      book_context:
                        type: object
                        description: An object containing additional context on the type of the processing the <<glossary:Book>> will go through.
                        properties:
                          uuid:
                            type: string
                            description: The unique identifier of the Book's context.
                          book_uuid:
                            type: string
                            description: The unique identifier of the Book's context.
                          book_class:
                            type: string
                            description: The processing type of the book. Can be either 'COMPLETE' or 'INSTANT'.
                          created_ts:
                            type: string
                            description: A timestamp of when the <<glossary:Book>> was created.
                  message:
                    type: string
                    description: A textual description that indicates details about this response's status.
                    example: OK
              examples:
                Success:
                  value:
                    status: 200
                    response:
                      name: Example Book
                      created: '2023-07-31T15:59:51Z'
                      created_ts: '2023-07-31T15:59:51Z'
                      pk: 34101490
                      uuid: 52dfdb53-6652-4d3a-a3db-fe864c6ff2fb
                      owner_email: email@address.com
                      is_public: true
                      xid: null
                      book_type: DEFAULT
                      id: 34101490
                      book_context:
                        uuid: 7876239a-ff18-42f3-a6b8-66db5af2e26a
                        book_uuid: 68a101e1-591c-4b87-acf3-ab8a55ceb746
                        book_class: INSTANT
                        created_ts: '2023-07-31T15:59:51Z'
                    message: OK
        '400':
          description: Client Errors
          content:
            application/json:
              examples:
                Book not found:
                  value:
                    status: 400
                    code: 1401
                    response: null
                    message: Book not found
                    meta:
                      status: 400
                      msg: Book not found
                      code: 1401
                Missing Required Parameters:
                  value:
                    status: 400
                    code: 1103
                    response: null
                    message: Required pk or book uuid
                    meta:
                      status: 400
                      msg: Required pk or book uuid
                      code: 1103
                No Permission:
                  value:
                    status: 400
                    code: 2102
                    response: null
                    message: No permission to access this book
                    meta:
                      status: 400
                      msg: No permission to access this book
                      code: 2102
                Incorrect book_type:
                  value:
                    status: 400
                    code: 2102
                    response: null
                    message: Book is not in MACHINE_ONLY context
                    meta:
                      status: 400
                      msg: Book is not in MACHINE_ONLY context
                      code: 2102
              schema:
                $ref: '#/paths/~1v1~1book~1remove/post/responses/400/content/application~1json/schema'
components:
  securitySchemes:
    oauth:
      type: oauth2
      description: 'OAuth 2.0 support via client credentials flow. See [here](doc:using-api-credentials) for usage information.

        '
      flows:
        clientCredentials:
          tokenUrl: https://auth.ocrolus.com/oauth/token
          scopes: {}