Upload a value

A value is raw binary data stored separately from object state. Uploading a value returns an opaque valueRef that state can reference, so large or binary payloads stay out of the inline state body.

Upload a binary blob for a fully qualified object name. The API returns an opaque valueRef that you can assign with Set object state, retrieve with Download a value, or remove with Delete a value.

Send the file as raw request bytes with Content-Type: application/octet-stream, not as JSON or Base64. The optional filename and filemimetype query parameters are stored as metadata and later returned through download response headers.

If the stored value cannot be found later, verify that subsequent requests use both the same fully qualified object and the exact valueRef returned by this endpoint. Use List stored values to inspect available references and metadata.

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

Query parameters#

  • objectstring
    Required

    Unique name of the object in the URL.

    format:
    abc:0-9@owner
  • filenamestring
    Optional

    Optional. Original file name (e.g. for display and match patterns).

    example: photo.png
  • filemimetypestring
    Optional

    Optional. Declared MIME type for the uploaded bytes.

    example: image/png

Headers#

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

    Your BigState API key.

    {{apiKey}}
  • Content-TypeRequired

    The upload body contains raw binary data.

    application/octet-stream

Need a session token? See Token sign in.

Request body#

Send the file as raw HTTP request bytes with Content-Type: application/octet-stream. Do not wrap the data in JSON.

Response parameters#

  • 200Response body · object

    Upload succeeded. Returns the new value reference to use in state `valueRef` and elsewhere.

    {

      "valueRef": "Mqn0WDHP8cuLYkMIjxAqmSdz8vRkTDDhB5Ie6Sn3"

    }
    • valueRefstring

      Opaque id for this blob (use in `GET`/`DELETE` /v1/value and in object state).

  • 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 object name or upload parameters."

    }
    • errornumber

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

    • descstring

      Human-readable description of the error.

Examples#

Upload a value

POST raw file bytes (optional filename and filemimetype query params); response includes valueRef.

curl 'https://api.bigstate.dev/v1/value?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%3Avalueref%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6&filename=photo.png&filemimetype=image%2Fpng' \

  --request POST \

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

  --data-binary ''
ValueDownload

© 2024 BigState