AUDS: Arbitrary User Data Store

How it works

Your game sends data to AUDS and receives a short code in return. Any player with that code can retrieve the data, which makes sharing player creations as easy as sharing a string. AUDS is currently a prototype, and your game needs to be live on Poki to use it.

Good use cases

• Player-built levels shared by code
• Leaderboards
• Turn-based or asynchronous multiplayer state

API reference

Create userdata

Use this endpoint to create userdata. The <freeform-key> can be any label you choose to categorize your data (for example tests, levels, or maps).

POST https://auds.poki.io/v0/<your-poki-game-id>/userdata/<freeform-key>

Request body

{
  "data": {
    "tiles": [1, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0],
    "note": "data in userdata is freeform, can be anything."
  },
  "values": {
    "levelname": "Test level",
    "type": "arena-1v1",
    "note": "'values' can only be key/value pairs where values can only be string, number, or boolean"
  }
}

Example request

const body = {
  data: {
    tiles: [1, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0],
    note: 'data in userdata is freeform, can be anything.'
  },
  values: {
    levelname: 'Test level',
    type: 'arena-1v1',
    note: "'values' can only be key/value pairs where values can only be string, number, or boolean"
  }
};

const requestOptions = {
  method: 'POST',
  body: JSON.stringify(body),
};

fetch('https://auds.poki.io/v0/use-your-poki-game-id/userdata/tests', requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Example response

{
  "id": "ce702oq1gkcvlv1tmlgg",
  "secret": "Qn8iO6bQVlGyVPkJhoi4oHwufb6GWgpgyedP5cO3fB39rzwTJZwg7N2n7GbLU3aG",
  "meta": {
    "revision": 1,
    "created_at": "2022-12-05T14:34:11.67798351Z",
    "expires_at": "2023-12-05T14:34:11.67798351Z",
    "expires_in": 31536000
  },
  "values": {
    "levelname": "Test level",
    "note": "'values' can only be key/value pairs where values can only be string, number, or boolean",
    "type": "arena-1v1"
  }
}

Fetch userdata by ID

Use this endpoint to retrieve a previously created userdata entry by its id.

GET https://auds.poki.io/v0/<your-poki-game-id>/userdata/<freeform-key>/<id>

Example request

fetch('https://auds.poki.io/v0/use-your-poki-game-id/userdata/tests/ce702oq1gkcvlv1tmlgg')
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Example response

{
  "id": "ce702oq1gkcvlv1tmlgg",
  "meta": {
    "revision": 1,
    "created_at": "2022-12-05T14:34:11.677983Z",
    "expires_at": "2023-12-05T14:37:02.733083Z",
    "expires_in": 31536000
  },
  "values": {
    "levelname": "Test level",
    "note": "'values' can only be key/value pairs where values can only be string, number, or boolean",
    "type": "arena-1v1"
  },
  "data": {
    "note": "data in userdata is freeform, can be anything.",
    "tiles": [1, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 1, 0, 0, 1, 0]
  }
}

Get list of userdata

Use this endpoint to list userdata. You can optionally filter and sort the results.

GET https://auds.poki.io/v0/<your-poki-game-id>/userdata/<freeform-key>?q=type:arena-1v1&sort=key&includedata

Supported query parameters

Example request

fetch('https://auds.poki.io/v0/use-your-poki-game-id/userdata/tests?q=type:arena-1v1')
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Example response

{
  "total": 1,
  "items": [
    {
      "id": "ce702oq1gkcvlv1tmlgg",
      "meta": {
        "revision": 1,
        "created_at": "2022-12-05T14:34:11.677983Z",
        "expires_at": "2023-12-05T14:34:11.677983Z",
        "expires_in": 31536000
      },
      "values": {
        "levelname": "Test level",
        "note": "'values' can only be key/value pairs where values can only be string, number, or boolean",
        "type": "arena-1v1"
      }
    }
  ]
}

Update userdata by ID with secret

To update userdata, you must supply the secret you received during creation, or your admin token through the Authorization header. This endpoint only updates the keys you provide. Omitted fields remain unchanged.

POST https://auds.poki.io/v0/<your-poki-game-id>/userdata/<freeform-key>/<id>

Request body

{
  "secret": "<SECRET_RECEIVED_ON_CREATE>",
  "data": {
    "tiles": [1, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 1, 0, 0, 1]
  },
  "values": {
    "levelname": "Test level (edited)",
    "type": "arena-1v1"
  }
}

Example request

const body = {
  secret: 'Qn8iO6bQVlGyVPkJhoi4oHwufb6GWgpgyedP5cO3fB39rzwTJZwg7N2n7GbLU3aG',
  data: {
    tiles: [1, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 1, 0, 0, 1]
  },
  values: {
    levelname: 'Test level (edited)',
    type: 'arena-1v1'
  }
};

const requestOptions = {
  method: 'POST',
  body: JSON.stringify(body),
};

fetch('https://auds.poki.io/v0/use-your-poki-game-id/userdata/tests/ce702oq1gkcvlv1tmlgg', requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Delete userdata by ID with secret

To delete userdata, you must supply the secret you received during creation, or your admin token through the Authorization header.

DELETE https://auds.poki.io/v0/<your-poki-game-id>/userdata/<freeform-key>/<id>

Request body

{
  "secret": "<SECRET_RECEIVED_ON_CREATE>"
}

Example request

const body = {
  secret: 'Qn8iO6bQVlGyVPkJhoi4oHwufb6GWgpgyedP5cO3fB39rzwTJZwg7N2n7GbLU3aG',
};

const requestOptions = {
  method: 'DELETE',
  body: JSON.stringify(body),
};

fetch('https://auds.poki.io/v0/use-your-poki-game-id/userdata/tests/ce702oq1gkcvlv1tmlgg', requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Increment a counter value

Use this endpoint to increment a numeric counter inside the values object. This is meant for public counters (for example play-count) and does not require the secret like the update endpoint does.

POST https://auds.poki.io/v0/<your-poki-game-id>/userdata/<freeform-key>/<id>/_increment?key=<value-key>

Notes

• The key must contain count (for example play-count or count-score).
• The existing value must be a number.
• The counter increases by 1.
• The revision does not change; only updated_at changes.
• No request body is required.
• No secret or Authorization header is required for this endpoint.

Example request

fetch('https://auds.poki.io/v0/use-your-poki-game-id/userdata/tests/ce702oq1gkcvlv1tmlgg/_increment?key=play-count', {
  method: 'POST'
})
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));