Get an object

An object is a named resource whose definition describes the state it accepts. An object can represent a device, user location, counter, or any other stateful entity, including type, retention, and version-history settings.

Retrieve the current definition for a fully qualified object name. The response describes its value type, object and state lifetimes, state validity window, retained version depth, and optional metadata.

A 404 means no object exists under the supplied name. Use List objects to find names visible to the current API key, or Create or update an object to define one.

GET

{{host}}/v1/object?object={{object}}

VERB:GET

BASE URL:{{host}}/v1/object

QUERY STRING:?object={{object}}

Query parameters#

RequiredOptional

objectstring
Required
Unique name of the object in the URL.
format:
abc:0-9@owner

Headers#

RequiredOptional

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.

Response parameters#

200Response body · object
Current definition for the requested object.
- typenumber
  How values for this object are encoded on the wire.
  Values
  2 — JSON object
  3 — number
  4 — string
  5 — Base64 binary data
  default:
  2
- ttlnumber
  Time to live in seconds: lifetime of the object itself and all related data such as state.
  minValue:
  0
- validitynumber
  Duration of validity of state in seconds. The state can still be recovered afterward but is no longer considered useful or valid.
  example: Truck position valid for 10 minutes — use 600
  default:
  Not applied (no limit)
- versionDeepnumber
  Number of past version states kept in history.
  default:
  0 (no history stored)
- infoobject
  Metadata that helps readers understand what the object is used for.
  - info.namestring
    Human-readable name of the object.
  - info.descstring
    Description of the object.
  - info.exampleany
    Example of a typical value stored for this object.
401
Unauthorized.
403
Access denied. The caller does not have sufficient rights to perform this operation.
404
No object exists for the given name.
400Response body · object
Bad request.
```
{
  "error": 6,
  "desc": "Object must be formatted as object"
}
```
- errornumber
  Numeric error code. Use the response `desc` field for the human-readable explanation.
- descstring
  Human-readable description of the error.

Examples#

Get an object

Fetch the current definition for an object by its fully qualified name.


curl 'https://api.bigstate.dev/v1/object?object=Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6%3Aposition%40Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

Create or update Delete

Description
Query parameters
Headers
Response parameters
Examples