openapi: 3.1.0
x-stoplight:
  id: wvqf4vs7shjnu
info:
  title: Evently.cloud Preview
  version: 1.2.0
  summary: 'API for Evently clients to use to register new event types, append events and select existing events. Clients can subscribe to notifications of new events that match selectors.'
  description: |-
    Evently stores business events for later use in event sourcing applications. Events are stored in ledgers and retrieved with selectors. Clients can subscribe to real-time notifications of new events that match selectors. One can also download the ledger for other uses.

    This API is grouped in the following sections:

    * Registry - Events must be registered before use
    * Append - Append events to the ledger
    * Selectors - Select events from the ledger that match criteria
    * Notifications - Subscribe to new event notifications
    * Ledgers - Manage ledgers that hold events

    This API expresses capabilities using Level 3 REST profiles and patterns, a hypermedia API specification found at https://level3.rest.
  contact:
    name: Preview Support
    url: 'https://evently.cloud/preview'
    email: preview@evently.cloud
  termsOfService: 'https://evently.cloud/preview'
  license:
    name: CC-BY-NC-ND-4.0
    url: 'https://creativecommons.org/licenses/by-nc-nd/4.0/'
servers:
  - url: 'https://preview.evently.cloud'
tags:
  - name: ledgers
    description: Manage event ledgers
  - name: registry
    description: Event registry to manage entity event types
  - name: append
    description: Append events to the ledger
  - name: selectors
    description: Select events from the ledger
  - name: notify
    description: Notifications of new events in the ledger that match selectors
paths:
  /registry/register-event:
    get:
      summary: Event Registration Form
      tags:
        - ledgers
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
                  - '<https://level3.rest/patterns/list#add-entry-resource>'
            Link:
              schema:
                default:
                  - '</registry/entities>; rel="https://level3.rest/patterns/list/editable#adds-to-list"'
                type: array
      operationId: get-register-event-form
      description: 'Form to register an entity event. GET the schema, create a JSON object with it and POST it back this endpoint.'
      security:
        - opaque-token: []
    parameters: []
    post:
      summary: Register an Event Type
      tags:
        - ledgers
      operationId: post-register-event-form
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
              description: The URI of the registered event type.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entity:
                  type: string
                  maxLength: 80
                  pattern: '^[^\x00-\x1F\x80-\x9F]+$'
                event:
                  type: string
                  maxLength: 80
                  pattern: '^[^\x00-\x1F\x80-\x9F]+$'
              required:
                - entity
                - event
            examples:
              register-event:
                value:
                  entity: account
                  event: account-created
      description: 'Accepts a form object to register a new entity event type. This action is idempotent, so one can register the same event repeatedly without a failure response.'
      security:
        - opaque-token: []
  /registry/entities:
    get:
      summary: Entities with Registered Events
      tags:
        - registry
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/home>'
                  - '<https://level3.rest/patterns/list#list-resource>'
          content:
            application/json+hal:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
      operationId: get-registry-entities
      description: Get links to entities that have registered events.
      security:
        - opaque-token: []
  '/registry/entities/{entity}':
    get:
      summary: An Entity's Events
      tags:
        - registry
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/home>'
                  - '<https://level3.rest/patterns/list#list-resource>'
          content:
            application/json+hal:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
      operationId: get-registry-entity
      description: Get links to events registered to an entity.
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: entity
        in: path
        required: true
        description: entity name
  '/registry/entities/{entity}/{event}':
    get:
      summary: An Entity Event
      tags:
        - registry
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/data>'
                  - '<https://level3.rest/patterns/list#entry-resource>'
          content:
            application/json+hal:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
      operationId: get-registered-entity-event
      description: Get a registered entity event.
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: entity
        in: path
        required: true
        description: entity name
      - schema:
          type: string
        name: event
        in: path
        required: true
        description: event name
    delete:
      summary: Delete Entity Event
      tags:
        - registry
      operationId: delete-registered-entity-event
      responses:
        '204':
          description: No Content
      description: Deletes this entity event registration. Only succeeds if no events of this type have been appended to the ledger.
      security:
        - opaque-token: []
  /append/fact:
    get:
      summary: Append Factual Event Form
      tags:
        - append
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-append-fact-form
      description: Returns a JSON Schema form to append a factual event. Create an object matching this schema and POST it back.
    post:
      tags:
        - append
      summary: Append a Factual Event
      operationId: post-append-fact-form
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  eventId:
                    type: string
                    description: 'Generated event ID for this event. This value can be used in any API call that uses an ''after'' field to indicate an event or ledger mark in the ledger, such as selectors and serial append actions.'
                  idempotencyKey:
                    type: string
                    description: 'If an idempotencyKey was sent with the append request, it will be reflected here.'
                required:
                  - eventId
          headers:
            Location:
              schema:
                type: string
              description: A Selector that replays the entity's events after this new event.
      description: |-
        Append a factual event to the ledger. Factual events append without conditions such as selector state or entity sequence. Facts often capture external events like delivery service receipts and IoT signals.

        If your client has uncertain connectivity and wants to append the event multiple times to ensure success, send a unique, client-created `idempotencyKey` to identify this specific event in subsequent append attempts. Evently recommends using [Nano IDs](https://zelark.github.io/nano-id-cc/).
      security:
        - opaque-token: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                entity:
                  type: string
                  description: The name of the entity.
                key:
                  type: string
                  description: The entity's business identifier.
                event:
                  type: string
                  description: Name of the event being appended.
                meta:
                  type: object
                  description: 'Event metadata. Use properties that are common to all events, like correlationId, actor and causationId. Evently creates an append timestamp value automatically, so clients can omit putting a timestamp in `meta`.'
                data:
                  description: 'Event data can be any type of data, from a string to an object with multiple values. The data is specific to the entity event.'
                  type:
                    - string
                    - number
                    - boolean
                    - object
                    - array
                idempotencyKey:
                  type: string
                  minLength: 2
                  description: Unique key identifying the append event's idempotency. This key will instruct evently to ignore duplicate append submissions instead of sending an error response.
              required:
                - entity
                - key
                - event
                - meta
                - data
  /append/serial:
    get:
      summary: Append Serial Event Form
      tags:
        - append
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-append-serial-form
      description: Returns a JSON Schema form to append a serial event. Create an object matching this schema and POST it back.
    post:
      tags:
        - append
      summary: Append a Serial Event
      operationId: post-append-serial-form
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  eventId:
                    type: string
                    description: 'Generated event ID for this event. This value can be used in any API call that uses an ''after'' field to indicate an event or ledger mark in the ledger, such as selectors and serial append actions.'
                  idempotencyKey:
                    type: string
                    description: 'If an idempotencyKey was sent with the append request, it will be reflected here.'
                required:
                  - eventId
          headers:
            Location:
              schema:
                type: string
              description: A Selector that replays the entity's events after this new event.
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: string
                    description: 'Current contains the URL you should GET to catch up with new events before trying to append again, but this time with the most recent `previousEventId` from that selector''s last event.'
                  message:
                    type: string
                    description: Instructions on what to do with the `current` property.
                required:
                  - current
                  - message
      description: |-
        Append a serial event to the ledger. Serial events append only if they are the next event in an entity event sequence. The form requires a `previousEventId` for the latest event for an entity instance. This can be obtained from the result of a previous append operation or from a replay selector result.

        In order to append a serial event, an event must already be appended for the entity instance. This can be done by atomically appending a event which appends an event if none have been appended already, or a simple factual event if the client is unconcerned with other attempts to append to the specific entity instance.  

        If your client has uncertain connectivity and wants to append the event multiple times to ensure success, send a unique, client-created `idempotencyKey` to identify this specific event in subsequent append attempts. Evently recommends using [Nano IDs](https://zelark.github.io/nano-id-cc/).
      security:
        - opaque-token: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                entity:
                  type: string
                  description: The name of the entity.
                key:
                  type: string
                  description: The entity's business identifier.
                event:
                  type: string
                  description: Name of the event being appended.
                meta:
                  type: object
                  description: 'Event metadata. Use properties that are common to all events, like correlationId, actor and causationId. Evently creates an append timestamp value automatically, so clients can omit putting a timestamp in `meta`.'
                data:
                  description: 'Event data can be any type of data, from a string to an object with multiple values. The data is specific to the entity event.'
                  type:
                    - string
                    - number
                    - boolean
                    - object
                    - array
                previousEventId:
                  type: string
                  description: The event ID of the most recent event appended to this entity instance. This value is found in the last event of a replay selector result stream.
                idempotencyKey:
                  type: string
                  minLength: 2
                  description: Unique key identifying the append event's idempotency. This key will instruct evently to ignore duplicate append submissions instead of sending an error response.
              required:
                - entity
                - key
                - event
                - meta
                - data
                - previousEventId
    parameters: []
  /append/atomic:
    get:
      summary: Append Atomic Event Form
      tags:
        - append
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-atomic-append-form
      description: Returns a JSON Schema form to atomically append and event using a selector conditional. Create an object matching this schema and POST it back.
    post:
      summary: Atomic Append Event
      tags:
        - append
      operationId: post-atomic-append-form
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  eventId:
                    type: string
                    description: 'Generated event ID for this event. This value can be used in any API call that uses an ''after'' field to indicate an event or ledger mark in the ledger, such as selectors and serial append actions.'
                  idempotencyKey:
                    type: string
                    description: 'If an idempotencyKey was sent with the append request, it will be reflected here.'
                required:
                  - eventId
          headers:
            Location:
              schema:
                type: string
              description: An updated Selector that filters events after this new event.
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: string
                    description: 'Current contains the URL you should GET to catch up with new events before trying to append again, but this time with the `mark` from that selector''s footer.'
                  message:
                    type: string
                    description: Instructions on what to do with the `current` property.
                required:
                  - current
                  - message
      description: |-
        Append an event atomically to the ledger using a selector conditional. These events append only if the provided selector is quiescent, meaning it has no new events. This selector's quiescence is the condition required to append the event. The form requires a `selector` object with a `selectorId` indicating the selector and `mark` pointing to the ledger mark where the selector has been read up to.

        One can use either a replay or a filter selector as a condition for appending an event. The data for the `selector` object is found in the selector's footer object at the end of a selector event stream.

        If your client has uncertain connectivity and wants to append the event multiple times to ensure success, send a unique, client-created `idempotencyKey` to identify this specific event in subsequent append attempts. Evently recommends using [Nano IDs](https://zelark.github.io/nano-id-cc/).
      security:
        - opaque-token: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                entity:
                  type: string
                  description: The name of the entity.
                key:
                  type: string
                  description: The entity's business identifier.
                event:
                  type: string
                  description: Name of the event being appended.
                meta:
                  type: object
                  description: 'Event metadata. Use properties that are common to all events, like correlationId, actor and causationId. Evently creates an append timestamp value automatically, so clients can omit putting a timestamp in `meta`.'
                data:
                  description: 'Event data can be any type of data, from a string to an object with multiple values. The data is specific to the entity event.'
                  type:
                    - string
                    - number
                    - boolean
                    - object
                    - array
                selector:
                  type: object
                  required:
                    - selectorId
                    - mark
                  description: The selector used to atomically append this event. The data for this object is found in the footer of a selector event stream.
                  properties:
                    selectorId:
                      type: string
                    mark:
                      type: string
                idempotencyKey:
                  type: string
                  minLength: 2
                  description: Unique key identifying the append event's idempotency. This key will instruct evently to ignore duplicate append submissions instead of sending an error response.
              required:
                - entity
                - key
                - event
                - meta
                - data
                - selector
    parameters: []
  /selectors/replay:
    get:
      summary: Replay Events Selector Lookup
      tags:
        - selectors
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-replay-selector-lookup
      description: Lookup control used to select entity events to replay. Construct an object that matches this schema and POST it back to this location.
      security:
        - opaque-token: []
    post:
      summary: Replay Entity Events
      operationId: post-selector-replay-lookup
      responses:
        '200':
          description: OK
          headers:
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=representation
                  - return=minimal
              description: 'If the `Prefer` header was sent with the request, this will hold the preference that was applied.'
            Content-Location:
              schema:
                type: string
                format: uri
              description: The URL of the configured selector result.
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/info>'
                  - '<https://level3.rest/profiles/entity>'
            Link:
              schema:
                default:
                  - '</selectors/fetch/{start-info}>; rel="start"'
                  - '</selectors/fetch/{current-info}>; rel="current"'
                  - '</selectors/replay>; rel="https://level3.rest/profiles/lookup"'
                type: array
          content:
            application/x-ndjson:
              schema:
                type: any
        '303':
          description: See Other
          headers:
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=representation
                  - return=minimal
              description: 'If the `Prefer` header was sent with the request, this will hold the preference that was applied.'
            Location:
              schema:
                type: string
                format: uri
              description: The URI of the selector fetch resource that fulfills the POST form's specification.
      security:
        - opaque-token: []
      description: |-
        Submit a filter request to stream events from the ledger that match filter criteria. Use `after` to catch up on a previously-fetched selector by setting it to a ledger mark or event ID. The `limit` property controls how many events are returned in the selector.

        This resource redirects to a URL that contains the selector results. If the redirect approach is not suitable, send a `Prefer` header indicating your client wishes the selector result in the POST response.

        The default redirect approach works well with shared entities that change infrequently as they contain caching instructions to share with other clients. If the entity instance changes often then sending `Prefer: return=representation` will improve selector performance by skipping the redirect step at the cost of not utilizing the internet's caching services.

        The selector footer information (`selectorId`, `mark`) can be used to atomically append events using the /append/atomic endpoint.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entity:
                  type: string
                  description: The name of the entity type.
                keys:
                  type: array
                  description: An array of entity keys identifying the entity instances to replay events from.
                  items:
                    type: string
                events:
                  type: array
                  description: 'Filter the selected events to only include these event types. If this property is omitted, then all the event types for the entity are selected.'
                  items:
                    type: string
                after:
                  type: string
                  pattern: '^[0-9a-f]{24}(?:[0-9a-f]{8})?$'
                  description: Fetch events that occur after this ledger mark or event ID.
                limit:
                  type: integer
                  minimum: 1
                  description: Limit the number of returned events to this value.
              required:
                - entity
                - keys
            examples: {}
      parameters:
        - schema:
            type: string
            enum:
              - return=representation
              - return=minimal
          in: header
          name: Prefer
          description: Uses the "return" preference. Tells the selector to send the matching events in response to the POST request instead of sending a redirect to the fetch URL.
      tags:
        - selectors
    parameters: []
  /selectors/filter:
    get:
      summary: Filter Events Selector Lookup
      tags:
        - selectors
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-filter-selector-lookup
      description: Lookup control used to select filtered events across all entities in the ledger. Construct an object that matches this schema and POST it back to this location.
      security:
        - opaque-token: []
    post:
      summary: Filter Events
      tags:
        - selectors
      operationId: post-selector-filter-lookup
      responses:
        '200':
          description: OK
          headers:
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=representation
                  - return=minimal
              description: 'If the `Prefer` header was sent with the request, this will hold the preference that was applied.'
            Content-Location:
              schema:
                type: string
                format: uri
              description: The URL of the configured selector result.
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/info>'
                  - '<https://level3.rest/profiles/entity>'
            Link:
              schema:
                default:
                  - '</selectors/fetch/{start-info}>; rel="start"'
                  - '</selectors/fetch/{current-info}>; rel="current"'
                  - '</selectors/filter>; rel="https://level3.rest/profiles/lookup"'
                type: array
          content:
            application/x-ndjson:
              schema:
                type: any
        '303':
          description: See Other
          headers:
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=representation
                  - return=minimal
              description: 'If the `Prefer` header was sent with the request, this will hold the preference that was applied.'
            Location:
              schema:
                type: string
                format: uri
              description: The URI of the selector fetch resource that fulfills the POST form's specification.
      security:
        - opaque-token: []
      description: |-
        Submit a filter selector request to stream events of specified entities from the ledger. Use `after` to catch up on a previously-fetched selector by setting it to a ledger mark or event ID. The `limit` property controls how many events are returned in the selector.

        This resource redirects to a URL that contains the selector results. If the redirect approach is not suitable, send a `Prefer` header indicating your client wishes the selector result in the POST response.

        The default redirect approach works well with shared entities that change infrequently as they contain caching instructions to share with other clients. If the entity instance changes often then sending `Prefer: return=representation` will improve selector performance by skipping the redirect step at the cost of not utilizing the internet's caching services.

        The selector footer information (`selectorId`, `mark`) can be used to atomically append events using the /append/atomic endpoint.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                meta:
                  $ref: '#/components/schemas/sql-jsonpath-query'
                data:
                  type: object
                  description: Filter by event data values. Keys are entity names; values are objects whose keys are event names and values are SQL JSONPath queries.
                  additionalProperties:
                    type: object
                    description: Keys are event names. Values are SQL JSONPath Query objects.
                    additionalProperties:
                      $ref: '#/components/schemas/sql-jsonpath-query'
                after:
                  type: string
                  pattern: '^[0-9a-f]{24}(?:[0-9a-f]{8})?$'
                  description: Fetch events that occur after this ledger mark or event ID.
                limit:
                  type: integer
                  minimum: 1
                  description: Limit the number of returned events to this value.
            examples:
              cold days:
                value:
                  data:
                    thermostat:
                      temperature-recorded:
                        query: $.celsius ? (@ < 10.0)
                  meta:
                    query: $.correlationId (@==$cId)
                    vars:
                      cId: 44rugtj5nfgn445
                  after: 0005d2bfb29a03795f574859cb0687dc
                  limit: 1
        description: ''
      parameters:
        - schema:
            type: string
            enum:
              - return=representation
              - return=minimal
          in: header
          name: Prefer
          description: Uses the "return" preference. Tells the selector to send the matching events in response to the POST request instead of sending a redirect to the fetch URL.
    parameters: []
  '/selectors/fetch/{selector-info}.ndjson':
    get:
      summary: Fetch a Selector file
      tags:
        - selectors
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/info>'
                  - '<https://level3.rest/profiles/entity>'
            Link:
              schema:
                default:
                  - '</selectors/fetch/{start-info}>; rel="start"'
                  - '</selectors/fetch/{current-info}>; rel="current"'
                  - '</selectors/{selector-type}>; rel="https://level3.rest/profiles/lookup"'
                type: array
          content:
            application/x-ndjson:
              schema:
                type: any
      operationId: get-selector-fetch
      description: |-
        Fetch a selector result as configured by a selector lookup. This resource URI is provided by replay and filter selector lookups.

        This resource returns a newline-delimited JSON stream of the events, ordered by their append sequence. The last line of the response is a footer object. The footer contains data about the selector and links to selectors that will fetch all the matching events from the start of the ledger as well as a link to the current events that match the selector, but occurred after this selector was fetched.
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: selector-info
        description: Selector info identifier
        in: path
        required: true
  /ledgers:
    get:
      summary: Ledger Info
      tags:
        - ledgers
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/home>'
      operationId: get-ledgers
      description: 'Information about the ledgers, including links to download and reset actions.'
  /ledgers/download:
    get:
      summary: Download Ledger Form
      tags:
        - ledgers
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-ledger-download-form
      description: Download the entire ledger or the ledger after a specified ledger mark / event ID.
    post:
      summary: Submit Download Ledger Form
      tags:
        - ledgers
      operationId: post-download-ledger-form
      responses:
        '200':
          description: OK
          headers:
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=representation
                  - return=minimal
              description: 'If the `Prefer` header was sent with the request, this will hold the preference that was applied.'
            Content-Location:
              schema:
                type: string
                format: uri
              description: The URL of the download ledger resource.
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/info>'
                  - '<https://level3.rest/profiles/entity>'
            Link:
              schema:
                default:
                  - '</ledgers/download/{start-info}>; rel="start"'
                  - '</ledgers/download/{current-info}>; rel="current"'
                  - '</ledgers/download>; rel="https://level3.rest/profiles/lookup"'
                type: array
          content:
            application/x-ndjson:
              schema:
                type: any
        '303':
          description: See Other
          headers:
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=representation
                  - return=minimal
              description: 'If the `Prefer` header was sent with the request, this will hold the preference that was applied.'
            Location:
              schema:
                type: string
                format: uri
              description: The URI of the download ledger resource that fulfills the POST form's specification.
      security:
        - opaque-token: []
      description: Submit form to download a ledger either entirely or after a ledger mark / event ID.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                after:
                  type: string
                  pattern: '^[0-9a-f]{24}(?:[0-9a-f]{8})?$'
                  description: Download events that occur after this ledger mark or event ID.
                limit:
                  type: integer
                  minimum: 1
                  description: Limit the number of returned events to this value.
            examples:
              download-all:
                value: {}
              download-after:
                value:
                  after: 0005c7f976b819003a78cb08
      parameters:
        - schema:
            type: string
            enum:
              - return=representation
              - return=minimal
          in: header
          name: Prefer
          description: Uses the "return" preference. Tells the download resource to send the ledger in response to the POST request instead of sending a redirect to the download URL.
  '/ledgers/download/{download-info}.ndjson':
    get:
      summary: Download a Ledger file
      tags:
        - ledgers
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/info>'
                  - '<https://level3.rest/profiles/entity>'
            Link:
              schema:
                default:
                  - '</ledgers/download/{start-info}>; rel="start"'
                  - '</ledgers/download/{current-info}>; rel="current"'
                  - '</ledgers/download>; rel="https://level3.rest/profiles/lookup"'
                type: array
          content:
            application/x-ndjson:
              schema:
                type: any
      operationId: get-ledger-download-data
      description: 'Download the ledger as configured by a download ledger form. The content is formatted as [newline-delimited JSON](http://ndjson.org) and can be streamed to disk or through a streaming processor.'
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: download-info
        description: Download info identifier
        in: path
        required: true
  /ledgers/reset:
    get:
      summary: Reset Ledger Form
      tags:
        - ledgers
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
      operationId: get-reset-ledger-form
      description: Create a ledger reset request with this form schema and POST it back.
    post:
      summary: Reset Ledger
      tags:
        - ledgers
      operationId: post-reset-ledger-form
      responses:
        '204':
          description: No Content
      security:
        - opaque-token: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                after:
                  type: string
                  pattern: '^[0-9a-f]{24}(?:[0-9a-f]{8})?$'
                  description: Remove all events that occur after this ledger mark or event ID.
            examples:
              reset-all:
                value: {}
              reset-after:
                value:
                  after: 0005c7f976b819003a78cb08
        description: 'To reset the entire ledger, send an empty JSON object ''{}''. To remove all events after a ledger mark or an event ID, send an object with an `after` property containing the mark/event ID.'
      description: 'Reset the ledger to remove events, either completely or after a specific point.'
  /notify/open-channel:
    get:
      summary: Open Channel Action
      tags:
        - notify
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/action>'
      operationId: get-open-channel-action
      description: POST an empty body to this resource to open a new notification channel.
    post:
      summary: Open Channel Action
      tags:
        - notify
      operationId: post-open-channel-action
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: The URI of the newly-opened notification channel.
      security:
        - opaque-token: []
      description: Open a new notification channel.
  '/notify/{channelId}':
    get:
      summary: A Notification Channel
      tags:
        - notify
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/nexus>'
            Link:
              schema:
                default:
                  - '</notify/{channelId}/subscribe>; rel="subscribe"'
                  - '</notify/{channelId}/subscriptions>; rel="subscriptions"'
                  - '</notify/{channelId}/sse>; rel="stream"'
                type: array
          content:
            application/json+hal:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
      operationId: get-channel
      description: Get links to events registered to an entity.
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: channelId
        in: path
        required: true
        description: The channel identifier.
  '/notify/{channelId}/subscribe':
    get:
      summary: Notify Subscription Form
      tags:
        - notify
      responses:
        '200':
          description: OK
          content:
            application/schema+json:
              schema:
                $ref: 'https://json-schema.org/draft-07/schema'
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/form>'
                  - '<https://level3.rest/patterns/list#add-entry-resource>'
            Link:
              schema:
                default:
                  - '</notify/{channelId}/subscriptions>; rel="https://level3.rest/patterns/list/editable#adds-to-list"'
                type: array
      operationId: get-notify-subscribe-form
      description: 'Form to subscribe to selector notifications. GET the schema, create a JSON object with it and POST it back this endpoint.'
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: channelId
        in: path
        required: true
        description: The channel's identifier.
    post:
      summary: Subscribe to a Selector's Notifications
      tags:
        - notify
      operationId: post-notify-subscribe-form
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
              description: The URI of the registered event type.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                selectorId:
                  type: string
                  maxLength: 80
                  pattern: '^[0-9A-Za-z_-]+$'
              required:
                - selectorId
        description: This form accepts a selectorId from an existing selector.
      description: 'Accepts a form object to subscribe to notifications of new events that match the given selector. This action is idempotent, so one can subscribe to the same selector repeatedly without a failure response.'
      security:
        - opaque-token: []
  '/notify/{channelId}/subscriptions':
    get:
      summary: A Channel's Selector Subscriptions
      tags:
        - notify
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/home>'
                  - '<https://level3.rest/patterns/list#list-resource>'
          content:
            application/json+hal:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
            application/json:
              schema:
                type: object
                properties: {}
      operationId: get-channel-subscriptions
      description: Get links to a channel's subscriptions.
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: channelId
        in: path
        required: true
        description: The channel identifier.
  '/notify/{channelId}/subscriptions/{subscriptionId}':
    get:
      summary: A Channel Selector Subscription
      tags:
        - notify
      responses:
        '200':
          description: OK
          headers:
            Profile:
              schema:
                type: array
                default:
                  - '<https://level3.rest/profiles/nexus>'
                  - '<https://level3.rest/patterns/list#entry-resource>'
          content:
            application/json+hal:
              schema:
                $ref: 'https://raw.githubusercontent.com/evently-cloud/hal-json-schema/draft-08_1/hal.json'
      operationId: get-selector-subscription
      description: Get a channel selector subscription.
      security:
        - opaque-token: []
    parameters:
      - schema:
          type: string
        name: channelId
        in: path
        required: true
        description: The channel identifier.
      - schema:
          type: string
        name: subscriptionId
        in: path
        required: true
        description: The subscription identifier.
    delete:
      summary: Unsubscribe from a Selector Notification Subscription
      tags:
        - notify
      operationId: delete-selector-subscription
      responses:
        '204':
          description: No Content
      description: Unsubscribes from notifications of new events that match this selector.
      security:
        - opaque-token: []
  '/notify/{channelId}/sse':
    parameters:
      - schema:
          type: string
        name: channelId
        in: path
        required: true
        description: The channel identifier.
    get:
      summary: Notify Channel Server-Sent Events Stream
      description: 'Listen to selector notification events. Each event is a comma-separated list of matching selectors from the subscription list. See https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events for details on how to consume this event stream.'
      tags:
        - notify
      responses:
        '200':
          description: OK
          content:
            text/event-stream:
              schema:
                type: string
      operationId: get-channel-sse
      security:
        - opaque-token: []
components:
  schemas:
    sql-jsonpath-query:
      type: object
      description: SQL JSONPath statement to filter meta object values.
      example: $.correlationId (@=="44rugtj5nfgn445")
      properties:
        query:
          type: string
          description: A JSONPath query statement. Can include named variables, like '$age' or '$orderNumber'.
        vars:
          type: object
          description: If the query contains named variables, they are stored in this object. The object keys are the variable names, without the preceding '$', like 'age' and 'orderNumber'.
      required:
        - query
  securitySchemes:
    opaque-token:
      type: http
      scheme: bearer
      description: 'Evently provides this token for those parts of the API that require access to your private events and other information. Sign up for an access token at https://evently.cloud'
