Create or update a delivery

A delivery is a configured channel that selects objects and routes their state updates to consumers. Deliveries decouple publishers from subscribers: publishers write state over HTTP, while deliveries decide who receives each update.

Creates or replaces the configuration identified by the delivery query parameter. The request body sets the display name, channel type (1 for WebSocket, 2 for HTTP, or 3 for file), and objects patterns whose updates are delivered.

A successful request returns 204 No Content. Review the object patterns before enabling delivery because "*" selects all objects; use Get a delivery to inspect the saved configuration or List deliveries to find identifiers.

If the request returns 400, verify the identifier, channel type, and required body fields. For 401 or 403, check the x-api-key header and whether that key can manage deliveries.

POST
{{host}}/v1/delivery?delivery={{delivery}}
VERB:POST
BASE URL:{{host}}/v1/delivery
QUERY STRING:?delivery={{delivery}}

Query parameters#

  • deliverystring
    Required

    Unique identifier of the delivery configuration in the URL.

    example: wsall

Headers#

Send these headers with the request. Names are case-insensitive per HTTP rules.
  • x-api-keyRequired

    Your BigState API key.

    {{apiKey}}
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

Need a session token? See Token sign in.

Request body#

  • WebSocket delivery for all objects
    {

      "name": "ws all objects",

      "type": 1,

      "objects": [

        "*"

      ]

    }

Request parameters#

  • namestring
    Required

    Human-readable name for this delivery configuration.

  • typenumber
    Required

    Channel used to push state updates to subscribers.

    Values

    • WS = 1
    • HTTP = 2
    • FILE = 3
  • objectsarray[string]
    Required

    Object name patterns (e.g. glob) whose state updates are sent through this delivery. Use "*" to include all objects.

Response parameters#

  • 204Response body · no content

    Delivery was created or updated. No response body.

  • 401

    Unauthorized.

  • 403

    Access denied. The caller does not have sufficient rights to perform this operation.

  • 400Response body · object

    Bad request.

    {

      "error": 6,

      "desc": "Invalid request"

    }
    • errornumber

      Numeric error code. Use the response `desc` field for the human-readable explanation.

    • descstring

      Human-readable description of the error.

Examples#

Create or update a delivery

Create or replace a delivery: WebSocket channel, human-readable name, and object patterns (e.g. all objects). Success: 204, no body.

curl https://api.bigstate.dev/v1/delivery?delivery=wsall \

  --request POST \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json' \

  --data '{

  "name": "ws all objects",

  "type": 1,

  "objects": [

    "*"

  ]

}'
DeliveryGet

© 2024 BigState