Akter

Actors

List an app's actors, read their command history and export their databases, run a command on an actor's files, and erase an actor for good.

List⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/actors
actors.listBearer token

List the app's stored actors a page at a time, across all 300 shards. Pass the previous page's next as after to continue.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

Query parameters

  • actorstring

    Only actors of this name in the app's contract, such as Room.

  • afterstring

    Where a page of actors stopped. Pass the previous page's next unchanged; its contents are not a contract.

  • environmentstring

    The environment whose actors to list, such as prod, when called at the Cloud API's URL. Defaults to prod. An app's own hostname lists its own environment's actors.

  • limitinteger

    At most this many actors, 1 to 500. Defaults to 500.

Response 200ActorPage

  • actorsExportedActor[]required
  • actors[].actorstringrequired

    The actor's name in the app's contract, such as Room.

  • actors[].keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

  • nextstring

    Where a page of actors stopped. Pass the previous page's next unchanged; its contents are not a contract.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

History⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/actors/{actor}/{key}/history
actors.historyBearer token

Read an actor's command journal, oldest first, a page at a time after a seq, optionally only since a time.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • keystringrequired

    The actor's key, as the app's contract encodes it.

Query parameters

  • afterinteger

    Only commands after this seq. Pass the previous page's next. Defaults to 0, the start.

  • limitinteger

    At most this many commands, 1 to 500. Defaults to 500.

  • sincestring

    Only commands recorded at or after this time.

Response 200CommandHistoryPage

  • entriesCommandEntry[]required
  • entries[].atstringrequired
  • entries[].commandstringrequired
  • entries[].commandIdstringrequired
  • entries[].exitstringrequired

    The command's outcome, as JSON text in the app's contract encoding.

  • entries[].payloadstringrequired

    The command's payload, as JSON text in the app's contract encoding.

  • entries[].principalstringrequired

    Who sent the command, as JSON text in the app's contract encoding.

  • entries[].seqintegerrequired

    The command's place in the actor's journal, counting from 1.

  • nextinteger

    The command's place in the actor's journal, counting from 1.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 410ActorErasedError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Erase⁠

DELETEhttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/actors/{actor}/{key}
actors.eraseBearer tokenSafe to retryAsks a person to confirm

Erase an actor for good: its files are released and its key is destroyed, so its database can never be read again and every later call to it answers ActorErasedError. Its forks are untouched. Erasing an erased actor succeeds again, so after a 503 run it again: the erase may have stopped after releasing the files and before destroying the key, which leaves the database readable until it finishes. A person confirms it.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • keystringrequired

    The actor's key, as the app's contract encodes it.

Response 204<No Content>

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 428ConfirmationRequiredError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Export shard⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/export/shards/{shard}
actors.exportShardBearer token

List the actors that have a database on one of the app's 300 shards.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • shardintegerrequired

    One of the app's 300 shards, 1 to 300.

Response 200ExportShardPage

  • actorsExportedActor[]required
  • actors[].actorstringrequired

    The actor's name in the app's contract, such as Room.

  • actors[].keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

  • computersExportedComputer[]

    The computers those actors keep, ordered by actor, key and name. Absent from a host that predates computers.

  • computers[].actorstringrequired

    The actor's name in the app's contract, such as Room.

  • computers[].checkpointstring

    The computer's newest checkpoint Akter recorded. It stays in Akter Cloud and can't be downloaded; absent before the first.

  • computers[].egressstring[]required

    The hosts the computer may reach. Never credentials.

  • computers[].imagestringrequired
  • computers[].keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

  • computers[].namestringrequired

    The computer's name, unique within its actor.

  • computers[].sizeobjectrequired
  • computers[].size.memoryMibintegerrequired
  • computers[].size.vcpunumberrequired

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Export snapshot⁠

POSThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/export/snapshots
actors.exportSnapshotBearer token

Take a consistent, decrypted snapshot of one actor's database for export, with its size and SHA-256. akter export does this for every actor.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

Request bodyExportedActor

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

Response 201ExportSnapshot

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • bytesintegerrequired
  • keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

  • sha256stringrequired

    A SHA-256 digest as 64 lowercase hex characters.

  • snapshotstringrequired

    Names one export snapshot of one actor.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 410ActorErasedError | ExportSnapshotGoneError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Export read⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/export/snapshots/{snapshot}
actors.exportReadBearer token

Read a range of at most 64 KiB of an export snapshot's bytes.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • snapshotstringrequired

    Names one export snapshot of one actor.

Query parameters

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

  • lengthintegerrequired

    How many bytes to read, 1 to 65536.

  • offsetintegerrequired

    The first byte to read.

Response 200binary

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 410ActorErasedError | ExportSnapshotGoneError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Export files⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/export/snapshots/{snapshot}/files
actors.exportFilesBearer token

List the files an export snapshot holds, a page at a time, by SHA-256 and size.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • snapshotstringrequired

    Names one export snapshot of one actor.

Query parameters

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • afterstring

    A SHA-256 digest as 64 lowercase hex characters.

  • keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

Response 200ExportFilePage

  • filesExportedFile[]required
  • files[].bytesintegerrequired
  • files[].sha256stringrequired

    A SHA-256 digest as 64 lowercase hex characters.

  • nextstring

    A SHA-256 digest as 64 lowercase hex characters.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 410ActorErasedError | ExportSnapshotGoneError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Export file read⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/apps/{app}/export/snapshots/{snapshot}/files/{sha256}
actors.exportFileReadBearer token

Read a range of at most 64 KiB of one file an export snapshot holds, decrypted; its bytes hash to the SHA-256 in the path. ExportSnapshotGoneError means the snapshot has expired or holds no file with that SHA-256.

Path parameters

  • appstringrequired

    An app's name, unique within its organization. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • sha256stringrequired

    A SHA-256 digest as 64 lowercase hex characters.

  • snapshotstringrequired

    Names one export snapshot of one actor.

Query parameters

  • actorstringrequired

    The actor's name in the app's contract, such as Room.

  • keystringrequired

    The actor's key, as the app's contract encodes it. The empty key is allowed.

  • lengthintegerrequired

    How many bytes to read, 1 to 65536.

  • offsetintegerrequired

    The first byte to read.

Response 200binary

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 410ActorErasedError | ExportSnapshotGoneError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError