Docs/Core Concepts/Archive & Delete

Archive & delete

Ptolemy distinguishes between soft deletion (archive) and permanent deletion (hard delete). Archives are reversible; hard deletes are not. Understanding the difference helps you choose the right operation for your use case.

Soft delete (archive)

Most resources support soft deletion via DELETE /{id}. This sets an archived_at timestamp on the record but preserves all data. Archived records:

Still exist

Archived records remain in the database and count toward your plan’s database item quota.

Hidden by default

List endpoints exclude archived records unless you pass ?archived=true or include archived_at in your filter conditions.

Restorable

Use POST /{id}/restore to clear archived_at and return the record to active status.

Archive an instrument

DELETE /v1/workspaces/acme-capital/instruments/bhp.ax

# Response:
HTTP/1.1 204 No Content

Restoring archived records

Any archived record can be restored using the POST /{id}/restore endpoint. Restoration clears archived_at and may backfill missing field values. The API returns 409 Conflict if:

The record is not currently archived
Restoring it would violate a uniqueness constraint (e.g. another record now has the same identifier)

Restore an instrument

POST /v1/workspaces/acme-capital/instruments/bhp.ax/restore

# Response:
HTTP/1.1 200 OK
{ /* full instrument object with archived_at: null */ }

Hard delete

Some resources support permanent deletion via DELETE /{id}?hard=true. Hard deletes are immediate and irreversible — there is no restore. Dependent records are cascaded according to the schema.

Hard deletes are permanent. Prefer archiving for most use cases. Use hard delete only when you need to permanently remove data and free up quota.

Resource	Soft delete	Hard delete	Cascade on hard delete
Instruments	Yes	Yes	Field values, tag assignments
Markets	Yes	Yes	Market listings, calendars
Market listings	Yes	No	—
Time series values	Yes	No	—
Instrument tags	Yes (archive)	Yes	Blocked if tag has children
Listing suspensions	No	Yes	—

Querying archived records

To include archived records in list or filter results, use ?archived=true on GET endpoints, or add an archived_at condition to your filter body:

List endpoints — include archived

GET /v1/workspaces/acme-capital/instruments?archived=true

Filter — archived instruments only

{
  "filter": {
    "and": [{ "field": "archived_at", "op": "is_null", "value": false }]
  }
}

Archived records still count toward your database item quota. If you need to free up quota, use hard delete (?hard=true) where supported.

Tag archive behaviour

Tags follow a slightly different pattern. Archiving a tag archives all its descendants automatically (since a tag’s parent chain must be active for the tag to be meaningful). Restoring a tag, however, only restores that specific tag — descendants must be restored individually.

Archived tags cannot be assigned to instruments, but existing assignments are preserved. In filter queries, archived tags match only when you explicitly include archived_at conditions.