Arkestro Events API

openapi: 3.2.0
info:
  version: '2.0'
  title: V2 Events 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: events
paths:
  /api/v2/events:
    get:
      summary: list events
      tags:
      - events
      parameters:
      - name: external_id
        in: query
        description: 'One or more `external_id` values to filter by. To pass multiple values, use repeated query params: `?external_id[]=EXT-001&external_id[]=EXT-002`.

          '
        required: false
        schema:
          type: string
      - 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:
                  events:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - description
                      - external_id
                      - status
                      - created_at
                      - currency
                      - business_unit
                      - creator
                      properties:
                        id:
                          type: integer
                        description:
                          type:
                          - string
                          - 'null'
                        name:
                          type: string
                        external_id:
                          type:
                          - string
                          - 'null'
                        status:
                          type: string
                          enum:
                          - draft
                          - open_for_bidding
                          - closed
                          - awarded
                          - open_for_questions
                          - ready_to_award
                          - unawarded
                        created_at:
                          type: string
                          format: date-time
                        currency:
                          type: string
                        tags:
                          type: array
                          items:
                            type: string
                          example:
                          - finance
                          - procurement
                        config:
                          type: object
                          required:
                          - supplier_quantity_enabled
                          properties:
                            supplier_quantity_enabled:
                              type: boolean
                          additionalProperties: false
                        business_unit:
                          type: object
                          required:
                          - id
                          - name
                          - unique_name
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            unique_name:
                              type:
                              - string
                              - 'null'
                        creator:
                          type: object
                          required:
                          - id
                          - email
                          properties:
                            id:
                              type: integer
                            email:
                              type:
                              - string
                              - 'null'
                      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:
                events:
                - id: 1
                  name: Apollo Hardware
                  description: An event to develop advanced space-grade fasteners and components.
                  external_id: APOLLO-EXT-001
                  status: draft
                  created_at: '2025-03-26T17:00:00.000Z'
                  currency: USD
                  tags:
                  - finance
                  - procurement
                  config:
                    supplier_quantity_enabled: false
                  business_unit:
                    id: 10
                    name: Aerospace Engineering
                    unique_name: aerospace_eng
                  creator:
                    id: 501
                    email: john.doe@abc.com
                - id: 2
                  name: Titanium Tools
                  description: Development of high-strength tools and equipment for aerospace applications.
                  external_id: TITANIUM-EXT-002
                  status: open_for_bidding
                  created_at: '2025-03-26T18:30:00.000Z'
                  currency: USD
                  tags:
                  - finance
                  config:
                    supplier_quantity_enabled: false
                  business_unit:
                    id: 15
                    name: Advanced Manufacturing
                    unique_name: adv_mfg
                  creator:
                    id: 502
                    email: jane.smith@acme.com
                - id: 3
                  name: Precision Fasteners
                  description: Creating a new line of precision-engineered bolts and screws.
                  external_id: PRECISION-EXT-003
                  status: awarded
                  created_at: '2025-03-27T09:15:00.000Z'
                  currency: USD
                  tags: []
                  config:
                    supplier_quantity_enabled: false
                  business_unit:
                    id: 20
                    name: Industrial Fasteners
                    unique_name: ind_fasteners
                  creator:
                    id: 503
                    email: sam.lee@xyz.com
                pagination:
                  limit: 3
                  offset: 10
                  total: 122
                  returned_count: 3
        '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 event
      tags:
      - events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: object
                  required:
                  - name
                  properties:
                    name:
                      type: string
                    description:
                      type: string
                    currency:
                      type: string
                    external_id:
                      type: string
                      description: A unique identifier for the event within your company.
                    descriptive_columns_handler:
                      type: string
                      enum:
                      - match
                      - replace
                      - union
                    automated:
                      type: boolean
                    business_unit:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                    source_event:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: integer
                    start_at:
                      type: string
                      format: date-time
                      description: Start of the first scheduled element of the cloned event — the question round when the source has one, otherwise the first bidding round. The rest of the source schedule is shifted by the same offset, preserving the gaps between elements. Only applies when cloning from a source_event. Must be an ISO 8601 datetime string in the format YYYY-MM-DDTHH:mm:ssZ (e.g. 2026-05-01T09:00:00Z or 2026-05-01T09:00:00+05:30) — a date-only value (e.g. 2026-05-01) is not accepted. Cannot be in the past. If not provided, defaults to 3 weeks from the current time.
                      example: '2026-05-01T09:00:00Z'
                    creator:
                      type: object
                      properties:
                        id:
                          type: integer
                        email:
                          type: string
                    tags:
                      type: array
                      description: Optional list of tags to apply. Overrides default creator tag inheritance. Pass empty array to set no tags.
                      items:
                        type: string
                      example:
                      - finance
                      - procurement
                    config:
                      type: object
                      properties:
                        supplier_quantity_enabled:
                          type: boolean
                      additionalProperties: false
                    accepted_currencies:
                      type: array
                      description: Optional array of accepted currencies with conversion rates
                      items:
                        type: object
                        required:
                        - quoting_currency
                        - conversion_rate
                        properties:
                          quoting_currency:
                            type: string
                            example: MXN
                          conversion_rate:
                            type: number
                            format: float
                            example: 20.5
                    supplier_contacts:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: Supplier Contact ID to be used for adding supplier_contact to the event shortlist
                          email:
                            type: string
                            deprecated: true
                            description: Deprecated field. Use 'id' to add supplier_contact to the event shortlist instead.
                    custom_value_fields:
                      type: array
                      items:
                        type: object
                        additionalProperties:
                          type: string
                    lots:
                      type: array
                      items:
                        type: object
                        required:
                        - name
                        - sno
                        properties:
                          name:
                            type: string
                          description:
                            type: string
                          sno:
                            type: integer
                          adder_custom_column_headers:
                            type: array
                            description: 'Adder columns to configure on this lot. Lot Assignment is implicit — the containing lot is the assignment. To share a column across multiple lots, include it in each lot''s adder_custom_column_headers.

                              '
                            items:
                              type: object
                              required:
                              - name
                              properties:
                                name:
                                  type: string
                                taxonomy:
                                  type:
                                  - string
                                  - 'null'
                                scope:
                                  type: string
                                  enum:
                                  - per_line
                              additionalProperties: false
                          line_items:
                            type: array
                            items:
                              type: object
                              required:
                              - sno
                              - name
                              - quantity
                              - extended_quantity
                              - price
                              - units
                              properties:
                                sno:
                                  type: integer
                                name:
                                  type: string
                                quantity:
                                  type: integer
                                extended_quantity:
                                  type: integer
                                price:
                                  type: number
                                  format: float
                                negotiation_starting_price:
                                  type:
                                  - number
                                  - 'null'
                                units:
                                  type: string
                                descriptive_attributes:
                                  type: object
                                  additionalProperties:
                                    type: string
                                descriptive_elements:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                    - name
                                    - value
                                    properties:
                                      name:
                                        type: string
                                      value:
                                        type: string
                                    additionalProperties: false
                              additionalProperties: false
                        additionalProperties: false
                  additionalProperties: false
              additionalProperties: false
            example:
              event:
                name: ERF013338 200007902
                external_id: ERF013338
                creator:
                  email: jane.doe@acme.com
                descriptive_columns_handler: union
                currency: USD
                accepted_currencies:
                - quoting_currency: MXN
                  conversion_rate: 20.5
                - quoting_currency: EUR
                  conversion_rate: 0.85
                tags:
                - finance
                - procurement
                config:
                  supplier_quantity_enabled: true
                business_unit:
                  id: 334
                source_event:
                  id: 58513
                start_at: '2026-05-01T09:00:00Z'
                supplier_contacts:
                - id: 5994
                - id: 4983
                custom_value_fields:
                - Site ID: CSD-1053
                lots:
                - name: Lot For RFQLine# 10_0_1
                  sno: 1
                  description: Lot For RFQLine# 10_0_1
                  adder_custom_column_headers:
                  - name: Freight Charges
                    taxonomy: freight_logistics
                    scope: per_line
                  line_items:
                  - name: FWG-103K34014XXSB
                    price: 0
                    extended_quantity: 1
                    sno: 1
                    descriptive_elements:
                    - name: Description
                      value: FLG,RFWN,A105N,34IN,75#,B
                    - name: Required Date
                      value: '2024-09-07'
                    - name: Extended Description
                      value: ''
                    - name: External Line Item ID
                      value: '10_0_1'
                    descriptive_attributes:
                      External Line Item ID: '10_0_1'
                    units: EA
                - name: Lot For RFQLine# 20_0_1
                  sno: 2
                  description: Lot For RFQLine# 10_0_1
                  line_items:
                  - name: FWN-304G32001SB
                    price: 0
                    extended_quantity: 1
                    sno: 2
                    descriptive_elements:
                    - name: Description
                      value: FLG,RFWN,304SS,32IN,150#,B
                    - name: Required Date
                      value: '2024-09-21'
                    - name: Extended Description
                      value: FLG,RFWN,304SS,32IN,150#,B
                    - name: External Line Item ID
                      value: '20_0_1'
                    descriptive_attributes:
                      External Line Item ID: '20_0_1'
                    units: EA
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    type: object
                    required:
                    - id
                    - name
                    - description
                    - external_id
                    - status
                    - created_at
                    - currency
                    - business_unit
                    - source_event
                    - creator
                    - team_members
                    - supplier_contacts
                    - custom_value_fields
                    - lots
                    - schedule
                    - exchange_rates
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      description:
                        type:
                        - string
                        - 'null'
                      external_id:
                        type:
                        - string
                        - 'null'
                      currency:
                        type: string
                      status:
                        type: string
                        enum:
                        - draft
                        - open_for_bidding
                        - closed
                        - awarded
                        - open_for_questions
                        - ready_to_award
                        - unawarded
                      created_at:
                        type: string
                        format: date-time
                      tags:
                        type: array
                        items:
                          type: string
                        example:
                        - finance
                        - procurement
                      config:
                        type: object
                        required:
                        - supplier_quantity_enabled
                        properties:
                          supplier_quantity_enabled:
                            type: boolean
                        additionalProperties: false
                      business_unit:
                        type: object
                        required:
                        - id
                        - name
                        - unique_name
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                          unique_name:
                            type:
                            - string
                            - 'null'
                      source_event:
                        type:
                        - object
                        - 'null'
                        required:
                        - id
                        properties:
                          id:
                            type: integer
                      creator:
                        type: object
                        required:
                        - id
                        - email
                        properties:
                          id:
                            type: integer
                          email:
                            type:
                            - string
                            - 'null'
                      team_members:
                        type: array
                        items:
                          type: object
                          required:
                          - id
                          - email
                          - role
                          properties:
                            id:
                              type: integer
                            email:
                              type:
                              - string
                              - 'null'
                            role:
                              type: string
                              enum:
                              - collaborator
                              - owner
                              - viewer
                      supplier_contacts:
                        type: array
                        items:
                          type: object
                          required:
                          - email
                          - status
                          properties:
                            email:
                              type:
                              - string
                              - 'null'
                            status:
                              type: string
                              enum:
                              - shortlisted
                              - not_answered
                              - bounced
                              - accepted
                              - rejected
                      custom_value_fields:
                        type: array
                        items:
                          type: object
                          required:
                          - id
                          - type_text
                          - value_text
                          properties:
                            id:
                              type: integer
                            type_text:
                              type: string
                            value_text:
                              type: string
                          additionalProperties: false
                      lots:
                        type: array
                        items:
                          type: object
                          required:
                          - id
                          - name
                          - description
                          - sno
                          - line_items
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            description:
                              type:
                              - string
                              - 'null'
                            sno:
                              type: integer
                            custom_column_headers:
                              type: array
                              description: 'Only descriptive headers are exposed.

                                '
                              items:
                                type: object
                                required:
                                - id
                                - display_text
                                - column_type
                                - data_type
                                - is_supplier_visible
                                - column_order_index
                                properties:
                                  id:
                                    type: integer
                                  display_text:
                                    type: string
                                  column_type:
                                    type: string
                                  data_type:
                                    type: string
                                  is_supplier_visible:
                                    type: boolean
                                  column_order_index:
                                    type: integer
                                  character_limit:
                                    type:
                                    - integer
                                    - 'null'
                                additionalProperties: false
                            adder_custom_column_headers:
                              type: array
                              description: 'Adder columns configured on this lot. An "adder" is a numeric pricing column (e.g. Freight, Duties, Tariffs) that suppliers fill in when submitting a quote and whose values are added to the line-item price to produce the total landed cost. Lot Assignment is implicit: an adder column applies to the lot it appears under. Event-wide adder columns created via the buyer UI surface as an entry on every lot.

                                '
                              items:
                                type: object
                                required:
                                - id
                                - name
                                - column_order_index
                                - taxonomy
                                - scope
                                properties:
                                  id:
                                    type: integer
                                  name:
                                    type: string
                                    description: Column Name (buyer-defined display text)
                                  column_order_index:
                                    type: integer
                                  taxonomy:
                                    type:
                                    - string
                                    - 'null'
                                    description: Cost Category key
                                  scope:
                                    type: string
                                    description: Cost Calculation (currently only 'per_line')
                                    enum:
                                    - per_line
                                additionalProperties: false
                            line_items:
                              type: array
                              items:
                                type: object
                                required:
                                - id
                                - name
                                - is_required
                                - sno
                                - descriptive_attributes
                                properties:
                                  id:
                                    type: integer
                                  name:
                                    type: string
                                  sno:
                                    type: integer
                                  is_required:
                                    type: boolean
                                  price:
                                    type:
                                    - string
                                    - 'null'
                                  negotiation_starting_price:
                                    type:
                                    - string
                                    - 'null'
                                  descriptive_attributes:
                                    type: object
         

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arkestro/refs/heads/main/openapi/arkestro-events-api-openapi.yml