LearnReferenceBlog
Protocol

Entity Record

Entrypoint and profile for a single user on the BAQ network.

{
  "entity": "maggie.baq.run",
  "previous_entities": [],
  "profile": {
    "name": "Maggie Blum"
  },
  "servers": [...]
}

A public Record­ that is returned during the discovery process­. It contains a user’s entity, public profile, and server endpoints.

Properties

  • entity Entity

    • Current entity representing the user.

  • previous_entities Entity[]

    • Every previous entity assumed by this user.

  • profile EntityRecordProfile

    • Simple public profile for this user.

  • servers EntityRecordServer[]

    • Servers to contact to interact with this user.

    • Should contain at least one server.

    • Items within should be presented in order of preference.

Notes

  • There can be only one Entity record for a given user.

  • The Entity record is the entrypoint to a user’s BAQ data. When a user moves to a new server, the Entity record is updated and propagated on the network.

  • The Entity record is created by the user’s server during initial sign-up.

Properties

  • avatar BlobLink optional

    • Public avatar for this user.

    • Maximum size of 256kB.

  • name string optional

    • Display name for this user.

    • Maximum length of 40 unicode code points.

  • bio string optional

    • Short introduction for this user.

    • Maximum length of 160 unicode code points.

  • website URI optional

    • External website or social media profile for this user.

  • location string optional

    • Physical location of the user in the world.

Properties

  • version string

    • Version of the API supported by this server.

    • Currently, all servers are version 1.0.0.

  • endpoints EntityRecordServerEndpoints

    • HTTP endpoints to communicate with this server.

The various HTTP endpoints to interact with the BAQ server.

Properties

  • auth URI

    • Authentication flow entrypoint.

    • URL template variables:

      • {record_id}: ID of the application record to authenticate.

  • new_record URI

    • Create a new record.

  • records URI

    • Query, filter, and sort records.

  • record URI

    • Fetch or update a single record.

    • URL template variables:

      • {entity}: Entity of the record’s author.

      • {record_id}: ID of the record.

  • record_versions URI

    • List record versions in chronological order.

    • URL template variables:

      • {entity}: Entity of the record’s author.

      • {record_id}: ID of the record.

  • record_version URI

    • Fetch a single record version.

    • URL template variables:

      • {entity}: Entity of the record’s author.

      • {record_id}: ID of the record.

      • {version_hash}: Hash of the version.

  • new_blob URI

    • Upload a new blob.

  • record_blob URI

    • Fetch a single blob from a record.

    • URL template variables:

      • {entity}: Entity of the record’s author.

      • {record_id}: ID of the record.

      • {blob_hash}: Hash of the blob.

      • {file_name}: Name of the file as specified in the record.

  • record_version_blob URI

    • Fetch a single blob from a record version.

    • URL template variables:

      • {entity}: Entity of the record’s author.

      • {record_id}: ID of the record.

      • {version_hash}: Hash of the version.

      • {blob_hash}: Hash of the blob.

      • {file_name}: Name of the file as specified in the record.

  • events URI

  • new_notification URI

    • Propagate a record in between servers.

  • server_info URI

    • Server metadata, including rate-limiting status.

Notes

  • The endpoint format can vary from one server to another. URI Template­ variables are used to build to actual URL to query. Each of these are valid values for the record endpoint:

    https://baq.run/api/julie/records/{entity}/{record_id}
https://julie.baqhost.org/records?entity={entity}&record={record_id}
https://freebaq.org/users/julie/{entity}/record?id={record_id}

This is what the full content of an Entity record might look like.

{
  "entity": "julie.baq.run",
  "previous_entities": [],
  "profile": {
    "avatar": {
      "hash": "401599ca6e41cef5625b48ba38f1e3cc4d68fecf0b45109bcbb1e4f7ba22c5e4",
      "type": "image/jpeg",
      "name": "avatar.jpg"
    },
    "name": "Julie"
  },
  "servers": [
    {
      "version": "1.0.0",
      "preference": 0,
      "endpoints": {
        "auth": "https://baq.run/julie/auth/{record_id}",
        "records": "https://baq.run/api/julie/records",
        "record": "https://baq.run/api/julie/records/{entity}/{record_id}",
        "record_versions": "https://baq.run/api/julie/records/{entity}/{record_id}/versions",
        "record_version": "https://baq.run/api/julie/records/{entity}/{record_id}/versions/{version_hash}",
        "new_record": "https://baq.run/api/julie/records",
        "record_blob": "https://baq.run/api/julie/records/{entity}/{record_id}/blobs/{blob_hash}/{file_name}",
        "record_version_blob": "https://baq.run/api/julie/records/{entity}/{record_id}/versions/{version_hash}/blobs/{blob_hash}/{file_name}",
        "new_blob": "https://baq.run/api/julie/blobs",
        "events": "https://baq.run/api/julie/events",
        "new_notification": "https://baq.run/api/julie/notifications",
        "server_info": "https://baq.run/api/julie/server"
      }
    }
  ]
}

To fetch a record, we use the endpoints map to build the URL to query. Here’s an example of how this could be done (the JavaScript SDK handles this automatically).

function fetchRecord(entityRecord, entity, recordId) {
  const server = entityRecord.content.servers[0];
  const endpoint = server.endpoints.record;
  const url = endpoint
    .replaceAll("{entity}", entity)
    .replaceAll("{record_id}", recordId);

  return fetch(url);
}
© 2025 Quentez