Skip to content

auds-banner

AUDS - Arbitrary User Data Store

This API is currently in development and subject to change. Do not use in production.


1. Create userdata

Use the following endpoint to create userdata. The <freeform-key> can be any label you choose to categorize your data (e.g. tests, levels, maps, etc.).

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 or number"
  }
}

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 or number'
  }
};

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 or number",
    "type": "arena-1v1"
  }
}

Returned secret

The response will include an id and a secret. The secret is never returned again, so make sure you store it if you plan to update this userdata later.


2. 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 or number",
    "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]
  }
}


3. Get list of userdata

Use the following 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

Parameter Description
q=key:value Filters the results by a values key. Only basic matching is supported right now. This will change.
sort=key Sorts results ascending by the given values key.
sort=-key Sorts results descending by the given values key.
includedata Includes the data field in the returned items.

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 or number",
        "type": "arena-1v1"
      }
    }
  ]
}


4. Update userdata by ID with secret

To update userdata, you must supply the secret you received during creation, or your admin token though the Authorization header. This endpoint will only update 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),
  // Or instead of the secret in the body:
  // headers: {
  //   'Authorization': 'AdminToken <your-admin-token>',
  // }
};

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));

Example response

{
  "id": "ce702oq1gkcvlv1tmlgg",
  "meta": {
    "revision": 2,
    "created_at": "2022-12-05T14:34:11.677983Z",
    "updated_at": "2022-12-05T14:41:58.223397772Z",
    "expires_at": "2023-12-05T14:41:58.223397772Z",
    "expires_in": 31536000
  },
  "values": {
    "levelname": "Test level (edited)",
    "type": "arena-1v1"
  }
}


5. Delete userdata by ID with secret

To delete userdata, you must supply the secret you received during creation, or your admin token though 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),
  // Or instead of the body:
  // headers: {
  //   'Authorization': 'AdminToken <your-admin-token>',
  // }
};

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));


Final Notes

  • Secrets: Store the secret in a secure location (like localStorage) if you plan to update or delete this entry later. This API will never return the secret again.
  • Prototype: The q parameter will change in upcoming versions. Use with caution.
  • Freeform keys: The segment after /userdata/ is entirely up to you. For example, tests, levels, or players.
  • Admin token: All update (PATCH, PUT) and delete (DELETE) requests can also be made with a Authorization: AdminToken <your-admin-token> header instead of the secret in the request body.