Arkestro corporate categories API

openapi: 3.2.0
info:
  version: '2.0'
  title: V2 corporate categories API
  description: 'The Arkestro API is used to manage aspects of your Arkestro instance without needing to have a user session.

    Our current API offering features endpoints that allow the creation and execution of an event.


    To get started, please generate an API Token.

    To generate an API Token your user must be an admin and you must request the feature be made available.

    Once enabled, you can go to your User Settings -> Personal Access Tokens and generate a new API token.  This API token will be used in your request

    header as an X-Token.


    Once you have an API Token you can make your first request.  A good starting point would be to request one of the index endpoints, such as:

    curl --location --request GET ''https://api.arkestro.com/api/v2/events'' --header ''Accept: application/json'' --header ''X-Token: <YOUR API TOKEN>'''
servers:
- url: https://api.arkestro.com
security:
- ApiKeyAuth: []
tags:
- name: corporate categories
  description: Categories represent item or service groupings used in various reports and programs
paths:
  /api/v2/corporate/categories:
    get:
      summary: list categories
      description: List all of the Categories under an organization
      tags:
      - corporate categories
      parameters:
      - name: sort_by
        in: query
        description: The field to sort results by. Defaults to `created_at`.
        required: false
        schema:
          type: string
          default: created_at
          enum:
          - created_at
          - updated_at
      - name: sort_order
        in: query
        description: The sorting order (`asc` for ascending, `desc` for descending). Defaults to `asc`.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: limit
        in: query
        description: The maximum number of results to return. Defaults to `20`, max `200`.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: offset
        in: query
        description: The number of results to skip before starting to collect the result set. Defaults to `0`.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  categories:
                    type: array
                    items:
                      type: object
                      description: Categories represent item or service groupings used in various reports and programs
                      required:
                      - id
                      - code
                      - description
                      - name
                      properties:
                        id:
                          type: integer
                          description: The Arkestro ID of the category
                        code:
                          type: string
                          description: The external id of the category
                        description:
                          type:
                          - string
                          - 'null'
                          description: The description of the category
                        name:
                          type:
                          - string
                          - 'null'
                          description: The name of the category
                      additionalProperties: false
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                        description: The number of records requested.
                      offset:
                        type: integer
                        description: The number of records skipped after filtering and sorting.
                      total:
                        type: integer
                        description: The total number of records available after filtering.
                      returned_count:
                        type: integer
                        description: The number of records returned in the current response.
                additionalProperties: false
              example:
                categories:
                - id: 1
                  code: category-code-1
                  name: Electronics
                  description: Electronic items and accessories
                - id: 2
                  code: category-code-2
                  name: Office Supplies
                  description: Office Supplies & Stationary
                pagination:
                  limit: 2
                  offset: 10
                  total: 122
                  returned_count: 2
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
    post:
      summary: create category
      description: Create a new category
      tags:
      - corporate categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  type: object
                  required:
                  - code
                  properties:
                    code:
                      type: string
                      description: The external id of the category
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the category
                    name:
                      type:
                      - string
                      - 'null'
                      description: The name of the category
                  additionalProperties: false
              additionalProperties: false
            example:
              category:
                code: office-supplies
                name: Office Supplies
                description: Supplies used for daily office operations
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  category:
                    type: object
                    description: Categories represent item or service groupings used in various reports and programs
                    required:
                    - id
                    - code
                    - description
                    - name
                    properties:
                      id:
                        type: integer
                        description: The Arkestro ID of the category
                      code:
                        type: string
                        description: The external id of the category
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the category
                      name:
                        type:
                        - string
                        - 'null'
                        description: The name of the category
                    additionalProperties: false
                additionalProperties: false
              example:
                category:
                  id: 1
                  code: office-supplies
                  name: Office Supplies
                  description: Supplies used for daily office operations
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
  /api/v2/corporate/categories/{id}:
    get:
      summary: show category
      description: Get a category by id
      tags:
      - corporate categories
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  category:
                    type: object
                    description: Categories represent item or service groupings used in various reports and programs
                    required:
                    - id
                    - code
                    - description
                    - name
                    properties:
                      id:
                        type: integer
                        description: The Arkestro ID of the category
                      code:
                        type: string
                        description: The external id of the category
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the category
                      name:
                        type:
                        - string
                        - 'null'
                        description: The name of the category
                    additionalProperties: false
                additionalProperties: false
              example:
                category:
                  id: 1
                  code: office-supplies
                  name: Office Supplies
                  description: Supplies used for daily office operations
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
    patch:
      summary: update category
      description: Update a category by id
      tags:
      - corporate categories
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  type: object
                  properties:
                    code:
                      type: string
                      description: The external id of the category
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the category
                    name:
                      type:
                      - string
                      - 'null'
                      description: The name of the category
                  additionalProperties: false
              additionalProperties: false
            example:
              category:
                id: 1
                code: updated-office-supplies
                name: Updated Office Supplies Name
                description: Updated Supplies Description
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  category:
                    type: object
                    description: Categories represent item or service groupings used in various reports and programs
                    required:
                    - id
                    - code
                    - description
                    - name
                    properties:
                      id:
                        type: integer
                        description: The Arkestro ID of the category
                      code:
                        type: string
                        description: The external id of the category
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the category
                      name:
                        type:
                        - string
                        - 'null'
                        description: The name of the category
                    additionalProperties: false
                additionalProperties: false
              example:
                category:
                  id: 1
                  code: updated-office-supplies
                  name: Updated Office Supplies Name
                  description: Updated Supplies Description
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
    delete:
      summary: delete category
      description: Delete a category by id
      tags:
      - corporate categories
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The resource was deleted successfully.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                additionalProperties: false
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '500':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                additionalProperties: false
                properties:
                  error:
                    type: string
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Token