Developers · Resources

Resources

9 resources, 39 endpoints — every one documented straight from the route code, with a curl example you can copy, paste and run.

Resource

Entities

Legal-entity records (the Alethia entity register). Reads are workspace-scoped passthroughs of the stored documents; mutations run through a dedicated idempotent, revision-fenced command layer rather than the generic CRUD helpers. Restricted entities are hidden from keys without the restricted_records capability.

GET/api/v1/entitiesList entities

Lists the workspace's entities ordered by document id, with cursor paging. Records with restricted: true are filtered out unless the key has the restricted_records capability; stale registryCheck evidence is stripped from each record.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: Entity[], nextCursor: string | null }. Each element: The stored entity document: id plus every persisted field (the create/patch fields above, plus server-stamped slug, revision, workspaceId, createdAt, updatedAt and provenance fields). registryCheck (Companies House evidence) is included only while the evidence is current — stale evidence is stripped by stripNonCurrentEntityRegistryCheck.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid pagination cursor.	The cursor is malformed or was tampered with.
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/entities" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/entitiesCreate an entity

Creates an entity through the idempotent entity-mutation command. Requires an Idempotency-Key header; replays of the same key + body return the original result with Idempotency-Replayed: true. displayName defaults to legalName; jurisdiction defaults to "Other", entityType to "OTHER", status to "active". Unknown keys and server-owned fields are rejected (422). Emits an entity.created webhook via the durable outbox.

scope: writemodule: tithe

Request headers

Idempotency-Keyrequired: Client-chosen idempotency token, 8–200 chars, no control characters. Missing → 400.

Request body

Strict object (unknown keys rejected). Validated by PublicApiEntityCreateDataSchema.

Field	Type	Required	Description
legalName	string	Required	Legal name, 1–300 chars. The route pre-checks presence and returns 422 with fields.legalName when missing/blank.
displayName	string	Optional	Display name, 1–200 chars. Defaults to legalName when omitted or blank.
jurisdiction	string	Optional	Jurisdiction. Defaults to "Other".Allowed: "UK", "Luxembourg", "Jersey", "Guernsey", "Isle of Man", "Ireland", "Netherlands", "Belgium", "France", "Germany", "Austria", "Switzerland", "Liechtenstein", "Spain", "Portugal", "Italy", "Malta", "Cyprus", "Greece", "Poland", "Czechia", "Slovakia", "Hungary", "Romania", "Bulgaria", "Croatia", "Slovenia", "Estonia", "Latvia", "Lithuania", "Denmark", "Sweden", "Finland", "Norway", "Iceland", "Cayman Islands", "British Virgin Islands", "Bermuda", "Gibraltar", "Mauritius", "Other"
jurisdictionCode	string	Optional	Stable ISO 3166-1 alpha-2 country scope; required for structured ISO 20275 legal forms.
entityType	string	Optional	Entity type. Defaults to "OTHER".Allowed: "UK_LTD", "UK_PLC", "UK_LLP", "UK_LP", "LU_SCSP", "LU_SCS", "LU_SARL", "LU_SA", "LU_RAIF", "LU_SECURITISATION", "JE_COMPANY", "JE_LP", "JE_UNIT_TRUST", "OTHER"
status	string	Optional	Lifecycle status. Defaults to "active".Allowed: "active", "dormant", "in_liquidation", "sold", "dissolved", "proposed", "historic", "advisory", "archived"
legalForm	string	Optional	Legal form label (max 160 chars).
legalFormElfCode	string	Optional	Country-scoped four-character ISO 20275 ELF code.
legalFormJurisdictionCode	string	Optional	GLEIF accepted legal jurisdiction (country or ISO 3166-2 subdivision) for the ELF identity.
legalFormVariantCode	string	Optional	Jurisdiction-qualified convenience variant key; never implies cross-country equivalence.
legalFormNameOriginal	string	Optional	Exact native/source or Custom/Other text (max 3000 chars).
legalFormFamily	string	Optional	Broad product behaviour family; unclassified is retained when no reviewed mapping exists.Allowed: "company", "partnership", "cooperative", "association", "foundation", "trust", "fund", "public-law-body", "sole-trader", "branch", "supranational-eu", "other", "unclassified"
legalFormSource	string	Optional	Structured legal-form provenance; product overlays are never represented as raw ISO labels.Allowed: "ISO_20275", "product_overlay", "custom"
legalFormSourceVersion	string	Optional	Pinned provenance version: ISO 20275 1.6 or the versioned product-overlay mapping.
registrationNumber	string	Optional	Registry number (max 100 chars).
registryType	string	Optional	Register family/code, distinct from the registration number (max 50 chars).
registryAuthority	string	Optional	Register court or authority (max 300 chars).
registeredSeat	string	Optional	Legal/statutory seat, distinct from postal address (max 300 chars).
headOfficeSiret	string	Optional	French head-office SIRET; distinct from SIREN and tax reference (max 50 chars).
rneRegistration	string	Optional	French RNE registration/evidence reference (max 300 chars).
rcsRegistration	string	Optional	French conditional RCS registration/city text (max 300 chars).
apeNafCode	string	Optional	French APE/NAF activity code (max 50 chars).
eori	string	Optional	Optional EORI identifier (max 50 chars).
economicIdentificationNumber	string	Optional	Optional German W-IdNr. (max 100 chars).
incorporationDate	string	Optional	ISO date (YYYY-MM-DD).
registeredOffice	object	Optional	Address object: line1 (required), line2, city, county, region, postalCode, optional ISO countryCode, and exact country text (required). Full-object replace.
taxReference	string	Optional	Tax reference (max 100 chars).
vatNumber	string	Optional	VAT number (max 100 chars).
lei	string	Optional	Legal Entity Identifier — exactly 20 letters/digits.
yearEnd	string	Optional	Accounting year end (max 100 chars).
region	string	Optional	Region label (max 120 chars).
businessPurpose	string	Optional	Business purpose (max 5,000 chars).
agmDate	string	Optional	AGM date text (max 200 chars).
fiscalYearEnd	string	Optional	Fiscal year end (max 32 chars).
internationalLocalCounsel	string	Optional	Local counsel (max 300 chars).
significantSubsidiary	boolean	Optional	Significant-subsidiary flag.
taxType	string	Optional	Tax type label (max 120 chars).
dbaNames	array<string>	Optional	Trading names (max 50, unique case-insensitively).
auditors	string	Optional	Auditors (max 500 chars).
administrators	string	Optional	Administrators (max 500 chars).
lawyers	string	Optional	Lawyers (max 500 chars).
registeredAgent	string	Optional	Registered agent (max 500 chars).
serviceProviderIds	array<string>	Optional	Person/entity ids of service providers (max 100, unique).
colour	string	Optional	Six-digit hex colour, e.g. #4A6741.
fundNav	object	Optional	Latest NAV snapshot: { value: number ≥ 0, currency: ISO-4217 code, asOf: ISO date }. Full-object replace.
fatcaCrs	object	Optional	FATCA/CRS classification: fatcaStatus, giin, crsStatus, crsClassification, selfCertifiedAt (ISO date), notes — at least one field. Full-object replace.
tags	array<string>	Optional	Tag ids (max 100, unique).
previousNames	array<object>	Optional	Previous names: { name (required), from?: ISO date, to?: ISO date } (max 100).
customFields	object	Optional	Workspace-defined custom fields: string values (max 2,000 chars), at most 100 keys.
restricted	boolean	Optional	Record-level ACL flag. Changing it requires the restricted_records capability.
viewerIds	array<string>	Optional	Explicit viewer ids for restricted records (max 500). Changing it requires the restricted_records capability.
notes	string	Optional	Free notes (max 10,000 chars).

Response

201 — The created entity record when the key also has read scope; otherwise only { id, revision? }. The stored entity document: id plus every persisted field (the create/patch fields above, plus server-stamped slug, revision, workspaceId, createdAt, updatedAt and provenance fields). registryCheck (Companies House evidence) is included only while the evidence is current — stale evidence is stripped by stripNonCurrentEntityRegistryCheck.

Headers: Idempotency-Replayed, ETag

Errors (11)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Idempotency-Key header is required.	The Idempotency-Key header is absent.
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
409	Entity conflict \| Entity limit reached. \| Idempotency key conflicts with an earlier request.	A conflicting entity exists, the free-tier entity cap is reached, or the Idempotency-Key was already used with a different request body.
503	Entity mutations are temporarily unavailable.	The workspace's entity-mutation mode is transitioning (Retry-After: 5 is set).
503	Entity state requires reconciliation.	Persisted entity/receipt state failed integrity checks (logged for operators).
503	Service unavailable	An unclassified server error occurred.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/entities" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2d6b7a-9d61-4e3a-8c2a-5e7b1f0a6c9d" \
  -d '{
  "legalName": "example"
}'

GET/api/v1/entities/{entityId}Get an entity

Reads one entity. Restricted entities are indistinguishable from absent ones for keys without restricted_records. The response carries an ETag holding the entity revision, usable in a later PATCH's If-Match.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
entityId	path	string	Required	Entity document id.

Response

200 — The stored entity document: id plus every persisted field (the create/patch fields above, plus server-stamped slug, revision, workspaceId, createdAt, updatedAt and provenance fields). registryCheck (Companies House evidence) is included only while the evidence is current — stale evidence is stripped by stripNonCurrentEntityRegistryCheck.

Headers: ETag

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/entities/entity_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/entities/{entityId}Update an entity

Optimistically-concurrent profile patch. Requires Idempotency-Key and If-Match (the entity revision, bare or quoted, e.g. "3"). On revision mismatch the route returns 412 with currentRevision in the body and an ETag of the current revision. null clears nullable optional fields. Emits entity.updated via the durable outbox.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
entityId	path	string	Required	Entity document id.

Request headers

Idempotency-Keyrequired: Client-chosen idempotency token, 8–200 chars. Missing → 400.
If-Matchrequired: Expected entity revision (numeric, optionally quoted). Missing → 428; malformed → 400.

Request body

Strict object (unknown keys rejected); at least one field. Validated by EntityProfilePatchSchema — identity fields are optional but not nullable; profile fields accept null to clear.

Field	Type	Required	Description
legalName	string	Optional	Legal name, 1–300 chars.
displayName	string	Optional	Display name, 1–200 chars.
jurisdiction	string	Optional	Jurisdiction.Allowed: "UK", "Luxembourg", "Jersey", "Guernsey", "Isle of Man", "Ireland", "Netherlands", "Belgium", "France", "Germany", "Austria", "Switzerland", "Liechtenstein", "Spain", "Portugal", "Italy", "Malta", "Cyprus", "Greece", "Poland", "Czechia", "Slovakia", "Hungary", "Romania", "Bulgaria", "Croatia", "Slovenia", "Estonia", "Latvia", "Lithuania", "Denmark", "Sweden", "Finland", "Norway", "Iceland", "Cayman Islands", "British Virgin Islands", "Bermuda", "Gibraltar", "Mauritius", "Other"
jurisdictionCode	string	Optional	Stable ISO 3166-1 alpha-2 country scope.
entityType	string	Optional	Entity type.Allowed: "UK_LTD", "UK_PLC", "UK_LLP", "UK_LP", "LU_SCSP", "LU_SCS", "LU_SARL", "LU_SA", "LU_RAIF", "LU_SECURITISATION", "JE_COMPANY", "JE_LP", "JE_UNIT_TRUST", "OTHER"
status	string	Optional	Lifecycle status.Allowed: "active", "dormant", "in_liquidation", "sold", "dissolved", "proposed", "historic", "advisory", "archived"
legalForm	string\| null	Optional	Legal form label (max 160 chars).
legalFormElfCode	string\| null	Optional	Country-scoped four-character ISO 20275 ELF code.
legalFormJurisdictionCode	string\| null	Optional	GLEIF accepted legal jurisdiction (country or ISO 3166-2 subdivision) for the ELF identity.
legalFormVariantCode	string\| null	Optional	Jurisdiction-qualified convenience variant key; never implies cross-country equivalence.
legalFormNameOriginal	string\| null	Optional	Exact native/source or Custom/Other text (max 3000 chars).
legalFormFamily	string\| null	Optional	Broad product behaviour family; unclassified is retained when no reviewed mapping exists.Allowed: "company", "partnership", "cooperative", "association", "foundation", "trust", "fund", "public-law-body", "sole-trader", "branch", "supranational-eu", "other", "unclassified"
legalFormSource	string\| null	Optional	Structured legal-form provenance; product overlays are never represented as raw ISO labels.Allowed: "ISO_20275", "product_overlay", "custom"
legalFormSourceVersion	string\| null	Optional	Pinned provenance version: ISO 20275 1.6 or the versioned product-overlay mapping.
registrationNumber	string\| null	Optional	Registry number (max 100 chars).
registryType	string\| null	Optional	Register family/code, distinct from the registration number (max 50 chars).
registryAuthority	string\| null	Optional	Register court or authority (max 300 chars).
registeredSeat	string\| null	Optional	Legal/statutory seat, distinct from postal address (max 300 chars).
headOfficeSiret	string\| null	Optional	French head-office SIRET; distinct from SIREN and tax reference (max 50 chars).
rneRegistration	string\| null	Optional	French RNE registration/evidence reference (max 300 chars).
rcsRegistration	string\| null	Optional	French conditional RCS registration/city text (max 300 chars).
apeNafCode	string\| null	Optional	French APE/NAF activity code (max 50 chars).
eori	string\| null	Optional	Optional EORI identifier (max 50 chars).
economicIdentificationNumber	string\| null	Optional	Optional German W-IdNr. (max 100 chars).
incorporationDate	string\| null	Optional	ISO date (YYYY-MM-DD).
registeredOffice	object\| null	Optional	Address object: line1 (required), line2, city, county, region, postalCode, optional ISO countryCode, and exact country text (required). Full-object replace.
taxReference	string\| null	Optional	Tax reference (max 100 chars).
vatNumber	string\| null	Optional	VAT number (max 100 chars).
lei	string\| null	Optional	Legal Entity Identifier — exactly 20 letters/digits.
yearEnd	string\| null	Optional	Accounting year end (max 100 chars).
region	string\| null	Optional	Region label (max 120 chars).
businessPurpose	string\| null	Optional	Business purpose (max 5,000 chars).
agmDate	string\| null	Optional	AGM date text (max 200 chars).
fiscalYearEnd	string\| null	Optional	Fiscal year end (max 32 chars).
internationalLocalCounsel	string\| null	Optional	Local counsel (max 300 chars).
significantSubsidiary	boolean\| null	Optional	Significant-subsidiary flag.
taxType	string\| null	Optional	Tax type label (max 120 chars).
dbaNames	array<string>\| null	Optional	Trading names (max 50, unique case-insensitively).
auditors	string\| null	Optional	Auditors (max 500 chars).
administrators	string\| null	Optional	Administrators (max 500 chars).
lawyers	string\| null	Optional	Lawyers (max 500 chars).
registeredAgent	string\| null	Optional	Registered agent (max 500 chars).
serviceProviderIds	array<string>\| null	Optional	Person/entity ids of service providers (max 100, unique).
colour	string\| null	Optional	Six-digit hex colour, e.g. #4A6741.
fundNav	object\| null	Optional	Latest NAV snapshot: { value: number ≥ 0, currency: ISO-4217 code, asOf: ISO date }. Full-object replace.
fatcaCrs	object\| null	Optional	FATCA/CRS classification: fatcaStatus, giin, crsStatus, crsClassification, selfCertifiedAt (ISO date), notes — at least one field. Full-object replace.
tags	array<string>	Optional	Tag ids (max 100, unique).
previousNames	array<object>\| null	Optional	Previous names: { name (required), from?: ISO date, to?: ISO date } (max 100).
customFields	object\| null	Optional	Workspace-defined custom fields: string values (max 2,000 chars), at most 100 keys.
restricted	boolean	Optional	Record-level ACL flag. Changing it requires the restricted_records capability.
viewerIds	array<string>	Optional	Explicit viewer ids for restricted records (max 500). Changing it requires the restricted_records capability.
notes	string\| null	Optional	Free notes (max 10,000 chars).

Response

200 — The updated entity record when the key also has read scope; otherwise only { id, revision? }. The stored entity document: id plus every persisted field (the create/patch fields above, plus server-stamped slug, revision, workspaceId, createdAt, updatedAt and provenance fields). registryCheck (Companies House evidence) is included only while the evidence is current — stale evidence is stripped by stripNonCurrentEntityRegistryCheck.

Headers: Idempotency-Replayed, ETag

Errors (14)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Idempotency-Key header is required. \| If-Match must contain one numeric entity revision.	The Idempotency-Key header is absent, or If-Match is present but not a single non-negative integer.
428	If-Match header is required.	The If-Match header is absent.
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
412	Entity revision does not match.	If-Match does not equal the stored revision. Body carries currentRevision; ETag header carries the current revision.
409	Entity conflict \| Entity limit reached. \| Idempotency key conflicts with an earlier request.	A conflicting entity exists, the free-tier entity cap is reached, or the Idempotency-Key was already used with a different request body.
503	Entity mutations are temporarily unavailable.	The workspace's entity-mutation mode is transitioning (Retry-After: 5 is set).
503	Entity state requires reconciliation.	Persisted entity/receipt state failed integrity checks (logged for operators).
503	Service unavailable	An unclassified server error occurred.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/entities/entity_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2d6b7a-9d61-4e3a-8c2a-5e7b1f0a6c9d" \
  -H "If-Match: 3" \
  -d '{
  "legalName": "example"
}'

DELETE/api/v1/entities/{entityId}Delete an entity (approved deletions only)

Executes a previously APPROVED four-eyes deletion request. A valid entityDeletionRequests record (requested and approved in-app by two different members) must exist for the entity; without one — or when the entity is restricted and the key lacks restricted_records — the route returns 404. On success the entity and its references are removed and entity.deleted is emitted via the durable outbox.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
entityId	path	string	Required	Entity document id.

Response

200 — { deleted: true, id: string }

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	The entity does not exist, has no approved deletion request, or is a restricted record the key cannot access.
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/entities/entity_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

People

Directory of individuals and corporate contacts. PII fields (email, phone, nationality, countryOfResidence, residentialAddress) are ALWAYS masked in responses and REJECTED in request bodies — API keys carry no PII capability.

GET/api/v1/peopleList people

Lists people with cursor paging. Every record is passed through maskPerson, blanking the five PII fields.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: Person[], nextCursor: string | null }. Each element: id, fullName, type, firstName, lastName, companyId, title, isServiceProvider, status, tags, piiSeparated, workspaceId, createdAt, updatedAt, provenance fields — PII fields removed.

Errors (5)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/people" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/peopleCreate a person

Creates a person. Any supplied PII field is rejected with 422 ("PII is not accepted by this API key"). type defaults to "individual"; the server stamps piiSeparated: true. Fires the person.created webhook.

scope: writemodule: tithe

Request body

Strict object validated by PublicApiPersonCreateSchema.

Field	Type	Required	Description
fullName	string	Required	Full name, 1–300 chars.
type	string	Optional	Defaults to "individual".Allowed: "individual", "corporate"
firstName	string	Optional	Max 150 chars.
lastName	string	Optional	Max 150 chars.
companyId	string	Optional	Linked company (entity/person) id.
title	string	Optional	Job title, max 150 chars.
isServiceProvider	boolean	Optional	Marks the person as a service provider.
status	string	Optional	Directory status.Allowed: "active", "archived"
tags	array<string>	Optional	Tag ids (max 100, unique).

Response

201 — The created person record (id, submitted fields, piiSeparated: true, workspaceId, createdAt, updatedAt, createdVia: "api").

Errors (8)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/people" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": "example"
}'

GET/api/v1/people/{personId}Get a person

Reads one person, PII masked.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
personId	path	string	Required	Person document id.

Response

200 — The person record with PII fields removed.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/people/person_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/people/{personId}Update a person

Merge-patches a person. PII fields are rejected with 422. Nullable fields (firstName, lastName, companyId, title) accept null to clear. Fires person.updated.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
personId	path	string	Required	Person document id.

Request body

Strict object, at least one field (PublicApiPersonPatchSchema).

Field	Type	Required	Description
fullName	string	Optional	Full name, 1–300 chars.
type	string	Optional	Person type.Allowed: "individual", "corporate"
firstName	string\| null	Optional	Max 150 chars; null clears.
lastName	string\| null	Optional	Max 150 chars; null clears.
companyId	string\| null	Optional	Linked company id; null clears.
title	string\| null	Optional	Max 150 chars; null clears.
isServiceProvider	boolean	Optional	Service-provider flag.
status	string	Optional	Directory status.Allowed: "active", "archived"
tags	array<string>	Optional	Tag ids (max 100, unique).

Response

200 — The merged person record, PII masked.

Errors (9)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/people/person_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": "example"
}'

DELETE/api/v1/people/{personId}Delete a person

Deletes a person. Fires person.deleted.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
personId	path	string	Required	Person document id.

Response

200 — { deleted: true, id: string }

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/people/person_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Deals

Acquisition-pipeline deals (the Pipeline/Socage module). Workflow fields — stage, locked, icSubmission, acquiringEntityId, parentHoldcoId, activity, foundationDesignId — are service-layer-owned: rejected as unknown keys on CREATE and silently stripped on PATCH, so stage transitions and IC state can only change through the app.

GET/api/v1/dealsList deals

Lists deals with cursor paging.

scope: readmodule: socage

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: Deal[], nextCursor: string | null }. Each element: The stored deal document: id plus the fields above, stage, activity (audit trail; the create route stamps an initial 'Deal added to the pipeline' entry), defaulted parties/tags arrays and GBP currency, any workflow fields set by the service layer (locked, icSubmission, acquiringEntityId, parentHoldcoId, reference, foundationDesignId), workspaceId and audit stamps (createdAt, updatedAt, createdVia: "api").

Errors (5)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/deals" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/dealsCreate a deal

Creates a deal. nation must be England, Wales or Scotland. stage (optional, default "identified") is validated against the workspace's RESOLVED pipeline — canonical plus custom stage ids. Domain defaults (parties/activity/tags arrays, GBP) and an initial activity entry are applied server-side. Fires deal.created.

scope: writemodule: socage

Request body

Strict object validated by PublicApiDealCreateSchema. Server-owned workflow fields (reference, locked, icSubmission, acquiringEntityId, parentHoldcoId, activity, foundationDesignId) are rejected as unknown keys.

Field	Type	Required	Description
name	string	Required	Deal name, 1–300 chars.
nation	string	Required	UK nation. Any other value → 422.Allowed: "England", "Wales", "Scotland"
stage	string	Optional	Pipeline stage id, validated against the workspace's resolved stages (canonical + custom). Defaults to "identified".
slug	string	Optional	URL slug (max 200 chars).
siteAddress	object	Optional	Address: line1 (required), line2, city, county, region, postalCode, country (required).
assetClass	string	Optional	Asset-class id from the workspace's ASSET_CLASS_LABELS set.
investmentType	string	Optional	Investment-type id from INVESTMENT_TYPE_LABELS.
proposedEntityName	string	Optional	Proposed acquiring-entity name (max 300 chars).
proposedEntityJurisdiction	string	Optional	Proposed entity jurisdiction (max 100 chars).
price	number	Optional	Price ≥ 0.
currency	string	Optional	Currency code (max 10 chars). Defaults to GBP on create.
siteSize	object	Optional	{ value: number ≥ 0, unit: sqm \| sqft \| acre }.
deposit	object	Optional	{ kind: percent \| amount, value: number ≥ 0 }.
purchaseConditions	array<object>	Optional	Array (max 300) of { id, label, met: boolean }.
targets	array<object>	Optional	Array (max 300) of milestones { id, label, kind: stage \| custom, stage?, targetDate?, actualDate? (ISO dates) }.
parties	array<object>	Optional	Array (max 300) of { role (deal-party role id), name, companyId?, companyName?, personId?, entityId?, contact? }.
keyDates	object	Optional	{ hotSigned?, exclusivityEnds?, targetExchange?, exchanged?, targetCompletion?, completed?, planningDecisionExpectedDate? } — all ISO dates.
appraisal	object	Optional	{ gdv?: number ≥ 0, totalCost?: number ≥ 0 }.
appraisalScenarios	array<object>	Optional	Array (max 50) of { name, gdv?, totalCost?, holdingYears? }.
source	string	Optional	Deal source (max 300 chars).
regionMarket	string	Optional	Region/market label (max 200 chars).
askingPrice	number	Optional	Asking price ≥ 0.
agreedPrice	number	Optional	Agreed price ≥ 0.
headlineMetricType	string	Optional	Headline metric type (max 100 chars).
headlineMetricValue	string	Optional	Headline metric value (max 100 chars).
unitCount	number	Optional	Unit count ≥ 0.
businessPlanSummary	string	Optional	Business-plan summary (max 5,000 chars).
keyRisk	string	Optional	Key risk (max 2,000 chars).
nextActionText	string	Optional	Next action (max 500 chars).
nextActionDueDate	string	Optional	ISO date.
hotsStatus	string	Optional	HoTs status id from HOTS_STATUS.
planningStatus	string	Optional	Planning status id from PLANNING_STATUS.
currentPlanningStatus	string	Optional	Current planning status id from CURRENT_PLANNING_STATUS_LABELS.
creditTerms	object	Optional	{ borrowerSponsor?, facilityType?, loanAmount?, ltv?, marginCoupon?, termMaturity?, seniority?, securityCollateral?, covenantSummary? }.
abortReason	string	Optional	Abort reason (max 1,000 chars).
ddStatus	string	Optional	Due-diligence status id from DD_STATUS.
legalStatus	string	Optional	Legal status id from LEGAL_STATUS.
priority	string	Optional	Priority id from DEAL_PRIORITY.
customFields	object	Optional	Workspace-defined custom fields: string \| number \| boolean \| null values, at most 100 keys.
dueDiligence	array<object>	Optional	Array (max 300) of { id, label, done: boolean, category? }.
tasks	array<object>	Optional	Array (max 300) of { id, title, dueDate? (ISO date), done: boolean }.
projectId	string	Optional	Linked project id.
tags	array<string>	Optional	Tag ids (max 100, unique).
colour	string	Optional	Six-digit hex colour.
notes	string	Optional	Free notes (max 10,000 chars).

Response

201 — The stored deal document: id plus the fields above, stage, activity (audit trail; the create route stamps an initial 'Deal added to the pipeline' entry), defaulted parties/tags arrays and GBP currency, any workflow fields set by the service layer (locked, icSubmission, acquiringEntityId, parentHoldcoId, reference, foundationDesignId), workspaceId and audit stamps (createdAt, updatedAt, createdVia: "api").

Errors (8)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/deals" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "nation": "England"
}'

GET/api/v1/deals/{dealId}Get a deal

Reads one deal (raw stored document).

scope: readmodule: socage

Parameters

Parameter	In	Type	Required	Description
dealId	path	string	Required	Deal document id.

Response

200 — The stored deal document: id plus the fields above, stage, activity (audit trail; the create route stamps an initial 'Deal added to the pipeline' entry), defaulted parties/tags arrays and GBP currency, any workflow fields set by the service layer (locked, icSubmission, acquiringEntityId, parentHoldcoId, reference, foundationDesignId), workspaceId and audit stamps (createdAt, updatedAt, createdVia: "api").

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/deals/deal_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/deals/{dealId}Update a deal

Merge-patches a deal. Accepts everything CREATE does (nullable to clear) plus reference; the workflow fields (stage, locked, icSubmission, acquiringEntityId, parentHoldcoId, activity, foundationDesignId) are ACCEPTED in the body — so read-modify-write round-trips don't 422 — but silently stripped from the write. Fires deal.updated.

scope: writemodule: socage

Parameters

Parameter	In	Type	Required	Description
dealId	path	string	Required	Deal document id.

Request body

Strict object, at least one field (PublicApiDealPatchSchema).

Field	Type	Required	Description
name	string	Optional	Deal name, 1–300 chars.
nation	string	Optional	Bounded string on PATCH (the England/Wales/Scotland value check runs on create only).
reference	string\| null	Optional	Deal reference (settable post-create; protected on create).
slug	string\| null	Optional	URL slug (max 200 chars).
siteAddress	object\| null	Optional	Address: line1 (required), line2, city, county, region, postalCode, country (required).
assetClass	string\| null	Optional	Asset-class id from the workspace's ASSET_CLASS_LABELS set.
investmentType	string\| null	Optional	Investment-type id from INVESTMENT_TYPE_LABELS.
proposedEntityName	string\| null	Optional	Proposed acquiring-entity name (max 300 chars).
proposedEntityJurisdiction	string\| null	Optional	Proposed entity jurisdiction (max 100 chars).
price	number\| null	Optional	Price ≥ 0.
currency	string\| null	Optional	Currency code (max 10 chars). Defaults to GBP on create.
siteSize	object\| null	Optional	{ value: number ≥ 0, unit: sqm \| sqft \| acre }.
deposit	object\| null	Optional	{ kind: percent \| amount, value: number ≥ 0 }.
purchaseConditions	array<object>	Optional	Array (max 300) of { id, label, met: boolean }.
targets	array<object>	Optional	Array (max 300) of milestones { id, label, kind: stage \| custom, stage?, targetDate?, actualDate? (ISO dates) }.
parties	array<object>	Optional	Array (max 300) of { role (deal-party role id), name, companyId?, companyName?, personId?, entityId?, contact? }.
keyDates	object\| null	Optional	{ hotSigned?, exclusivityEnds?, targetExchange?, exchanged?, targetCompletion?, completed?, planningDecisionExpectedDate? } — all ISO dates.
appraisal	object\| null	Optional	{ gdv?: number ≥ 0, totalCost?: number ≥ 0 }.
appraisalScenarios	array<object>	Optional	Array (max 50) of { name, gdv?, totalCost?, holdingYears? }.
source	string\| null	Optional	Deal source (max 300 chars).
regionMarket	string\| null	Optional	Region/market label (max 200 chars).
askingPrice	number\| null	Optional	Asking price ≥ 0.
agreedPrice	number\| null	Optional	Agreed price ≥ 0.
headlineMetricType	string\| null	Optional	Headline metric type (max 100 chars).
headlineMetricValue	string\| null	Optional	Headline metric value (max 100 chars).
unitCount	number\| null	Optional	Unit count ≥ 0.
businessPlanSummary	string\| null	Optional	Business-plan summary (max 5,000 chars).
keyRisk	string\| null	Optional	Key risk (max 2,000 chars).
nextActionText	string\| null	Optional	Next action (max 500 chars).
nextActionDueDate	string\| null	Optional	ISO date.
hotsStatus	string\| null	Optional	HoTs status id from HOTS_STATUS.
planningStatus	string\| null	Optional	Planning status id from PLANNING_STATUS.
currentPlanningStatus	string\| null	Optional	Current planning status id from CURRENT_PLANNING_STATUS_LABELS.
creditTerms	object\| null	Optional	{ borrowerSponsor?, facilityType?, loanAmount?, ltv?, marginCoupon?, termMaturity?, seniority?, securityCollateral?, covenantSummary? }.
abortReason	string\| null	Optional	Abort reason (max 1,000 chars).
ddStatus	string\| null	Optional	Due-diligence status id from DD_STATUS.
legalStatus	string\| null	Optional	Legal status id from LEGAL_STATUS.
priority	string\| null	Optional	Priority id from DEAL_PRIORITY.
customFields	object	Optional	Workspace-defined custom fields: string \| number \| boolean \| null values, at most 100 keys.
dueDiligence	array<object>	Optional	Array (max 300) of { id, label, done: boolean, category? }.
tasks	array<object>	Optional	Array (max 300) of { id, title, dueDate? (ISO date), done: boolean }.
projectId	string\| null	Optional	Linked project id.
tags	array<string>	Optional	Tag ids (max 100, unique).
colour	string\| null	Optional	Six-digit hex colour.
notes	string\| null	Optional	Free notes (max 10,000 chars).
stage	object	Optional	Accepted but IGNORED (service-layer-owned; silently stripped from the write).
locked	object	Optional	Accepted but IGNORED (silently stripped).
icSubmission	object	Optional	Accepted but IGNORED (silently stripped).
acquiringEntityId	object	Optional	Accepted but IGNORED (silently stripped).
parentHoldcoId	object	Optional	Accepted but IGNORED (silently stripped).
activity	object	Optional	Accepted but IGNORED (silently stripped).
foundationDesignId	object	Optional	Accepted but IGNORED (silently stripped).

Response

200 — The merged deal record.

Errors (9)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/deals/deal_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example"
}'

DELETE/api/v1/deals/{dealId}Delete a deal

Deletes a deal. Fires deal.deleted.

scope: writemodule: socage

Parameters

Parameter	In	Type	Required	Description
dealId	path	string	Required	Deal document id.

Response

200 — { deleted: true, id: string }

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/deals/deal_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Documents

Document metadata records. No module gate — documents belong to both persisted application modules (key scope + Enterprise are the authority). The API cannot upload bytes: created documents are metadata/link records and storagePath is always server-set to the empty string. Restricted documents are hidden from keys without restricted_records; setting restricted/viewerIds requires that capability.

GET/api/v1/documentsList documents

Lists documents with cursor paging. Records with restricted: true are filtered out unless the key has restricted_records.

scope: read

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: Document[], nextCursor: string | null }. Each element: id, name, category, kind, source, storagePath (always "" for API-created records), externalUrl, contentType, sizeBytes, projectId, entityId, entityIds, agreementId, dealId, tags, archived, restricted, viewerIds, workspaceId, audit stamps — plus any app-written fields on documents created in-app.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid pagination cursor.	The cursor is malformed or was tampered with.
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/documents" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/documentsRegister a document (metadata/link only)

Creates a metadata-only document record. category defaults to "other", kind to "uploaded", source to "link"; storagePath is forced to "". Setting restricted/viewerIds without the restricted_records capability → 403. Fires document.created.

scope: write

Request body

Strict object validated by PublicApiDocumentCreateSchema. storagePath, signing, sharePoint, currentVersionId, version, uploadedAt/uploadedBy are server-owned and rejected as unknown keys.

Field	Type	Required	Description
name	string	Required	Document name, 1–300 chars.
category	string	Optional	Defaults to "other".Allowed: "incorporation", "constitutional", "registers", "accounts", "tax", "board_minutes", "resolutions", "agreement", "filings", "kyc", "banking", "other"
kind	string	Optional	Defaults to "uploaded".Allowed: "uploaded", "generated"
source	string	Optional	Defaults to "link". The API cannot upload bytes regardless of this value.Allowed: "upload", "sharepoint", "link"
externalUrl	string	Optional	Link target URL (max 2,048 chars).
contentType	string	Optional	MIME type (max 200 chars).
sizeBytes	number	Optional	Size in bytes ≥ 0.
projectId	string	Optional	Linked project id.
entityId	string	Optional	Primary linked entity id.
entityIds	array<string>	Optional	Linked entity ids (max 200, unique).
agreementId	string	Optional	Linked agreement id.
dealId	string	Optional	Linked deal id.
tags	array<string>	Optional	Tag ids (max 100, unique).
archived	boolean	Optional	Archive flag.
restricted	boolean	Optional	Record-level ACL flag — requires restricted_records.
viewerIds	array<string>	Optional	Explicit viewer ids (max 500) — requires restricted_records.

Response

201 — The created document record (id, fields above, storagePath: "", workspaceId, audit stamps, createdVia: "api").

Errors (9)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
403	Forbidden: The restricted_records capability is required to change record access.	restricted or viewerIds supplied without the capability.
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/documents" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example"
}'

GET/api/v1/documents/{docId}Get a document

Reads one document record. Restricted records the key cannot access return 404.

scope: read

Parameters

Parameter	In	Type	Required	Description
docId	path	string	Required	Document id.

Response

200 — The document record.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/documents/doc_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/documents/{docId}Update a document

Merge-patches a document (same fields as create, nullable where clearable). Changing restricted/viewerIds requires restricted_records (403). Fires document.updated.

scope: write

Parameters

Parameter	In	Type	Required	Description
docId	path	string	Required	Document id.

Request body

Strict object, at least one field (PublicApiDocumentPatchSchema). Same field set as create; externalUrl, contentType, sizeBytes, projectId, entityId, agreementId, dealId accept null to clear.

Field	Type	Required	Description
name	string	Optional	Document name, 1–300 chars.
category	string	Optional	Category.Allowed: "incorporation", "constitutional", "registers", "accounts", "tax", "board_minutes", "resolutions", "agreement", "filings", "kyc", "banking", "other"
kind	string	Optional	Kind.Allowed: "uploaded", "generated"
source	string	Optional	Source.Allowed: "upload", "sharepoint", "link"
externalUrl	string\| null	Optional	Link URL; null clears.
contentType	string\| null	Optional	MIME type; null clears.
sizeBytes	number\| null	Optional	Size in bytes; null clears.
projectId	string\| null	Optional	Project id; null clears.
entityId	string\| null	Optional	Entity id; null clears.
entityIds	array<string>	Optional	Linked entity ids (max 200).
agreementId	string\| null	Optional	Agreement id; null clears.
dealId	string\| null	Optional	Deal id; null clears.
tags	array<string>	Optional	Tag ids (max 100).
archived	boolean	Optional	Archive flag.
restricted	boolean	Optional	Requires restricted_records.
viewerIds	array<string>	Optional	Requires restricted_records.

Response

200 — The merged document record.

Errors (10)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
403	Forbidden: The restricted_records capability is required to change record access.	restricted or viewerIds supplied without the capability.
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/documents/doc_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example"
}'

DELETE/api/v1/documents/{docId}Delete a document

Deletes a document record (metadata only). Fires document.deleted.

scope: write

Parameters

Parameter	In	Type	Required	Description
docId	path	string	Required	Document id.

Response

200 — { deleted: true, id: string }

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/documents/doc_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Properties

Real-estate object layer (PropCo/AssetCo holdings). READ-ONLY over the API — the routes export GET only.

GET/api/v1/propertiesList properties

Lists property records with cursor paging. Raw stored documents — the API applies no reshaping.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: Property[], nextCursor: string | null }. Each element (Property type): id, workspaceId, name, entityId, titleNumber, tenure, useClass, address, status, acquisitionDate, acquisitionPrice, acquisitionCurrency, valuation, leases, notes, audit stamps.

Errors (5)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/properties" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

GET/api/v1/properties/{propertyId}Get a property

Reads one property record.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
propertyId	path	string	Required	Property document id.

Response

200 — The property record (see list response).

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/properties/property_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Fund commitments

LP capital-account commitments into fund vehicles. READ-ONLY over the API (list only; no single-record route exists).

GET/api/v1/commitmentsList fund commitments

Lists commitment records with cursor paging. Raw stored documents — no reshaping.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: FundCommitment[], nextCursor: string | null }. Each element (FundCommitment type): id, workspaceId, fundEntityId, investorId, investorType (person | entity), amount, currency, commitmentDate, flows (capital calls/distributions), audit stamps.

Errors (5)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/commitments" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Cap table — Share classes

Share classes issued by an entity. entityId is checked to exist in the key's workspace on create and is immutable afterwards (a PATCH attempt is rejected as an unknown key).

GET/api/v1/cap-table/share-classesList share classes

Lists share classes with cursor paging.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: ShareClass[], nextCursor: string | null }. Each element: id plus the create fields below, workspaceId and audit stamps.

Errors (5)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/cap-table/share-classes" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/cap-table/share-classesCreate a share class

Creates a share class. entityId must reference an entity in the key's workspace (422 otherwise). votingRight defaults to "ordinary". Fires shareClass.created.

scope: writemodule: tithe

Request body

Strict object validated by PublicApiShareClassCreateSchema.

Field	Type	Required	Description
entityId	string	Required	Issuing entity id — must exist in this workspace.
name	string	Required	Class name, 1–200 chars.
votingRight	string	Optional	Defaults to "ordinary".Allowed: "ordinary", "non_voting", "multiple", "preference"
votesPerShare	number	Optional	Votes per share > 0.
parValue	number	Optional	Par value ≥ 0.
noParValue	boolean	Optional	No-par-value flag.
statedCapital	number	Optional	Stated capital ≥ 0.
currency	string	Optional	Currency code (max 10 chars).
authorisedShares	number	Optional	Authorised shares ≥ 0.
rights	object	Optional	{ preferredDividend?, liquidationPreference?, participating?, antiDilution? } — all booleans.
liquidationTerms	object	Optional	{ liquidationMultiple? ≥ 0, participationCap? ≥ 0, seniority?: number }.
description	string	Optional	Max 2,000 chars.

Response

201 — The created share-class record.

Errors (8)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/cap-table/share-classes" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "entityId": "entity_123",
  "name": "example"
}'

GET/api/v1/cap-table/share-classes/{id}Get a share class

Reads one share class.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
id	path	string	Required	Share-class document id.

Response

200 — The share-class record.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/cap-table/share-classes/id_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/cap-table/share-classes/{id}Update a share class

Merge-patches a share class. entityId is immutable (unknown key → 422). Numeric/text/object fields accept null to clear. Fires shareClass.updated.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
id	path	string	Required	Share-class document id.

Request body

Strict object, at least one field (PublicApiShareClassPatchSchema).

Field	Type	Required	Description
name	string	Optional	Class name, 1–200 chars.
votingRight	string	Optional	Voting right.Allowed: "ordinary", "non_voting", "multiple", "preference"
votesPerShare	number\| null	Optional	Votes per share > 0; null clears.
parValue	number\| null	Optional	Par value ≥ 0; null clears.
noParValue	boolean	Optional	No-par-value flag.
statedCapital	number\| null	Optional	Stated capital; null clears.
currency	string\| null	Optional	Currency code; null clears.
authorisedShares	number\| null	Optional	Authorised shares; null clears.
rights	object\| null	Optional	Rights object; null clears.
liquidationTerms	object\| null	Optional	Liquidation terms; null clears.
description	string\| null	Optional	Max 2,000 chars; null clears.

Response

200 — The merged share-class record.

Errors (9)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/cap-table/share-classes/id_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example"
}'

DELETE/api/v1/cap-table/share-classes/{id}Delete a share class

Deletes a share class. Fires shareClass.deleted.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
id	path	string	Required	Share-class document id.

Response

200 — { deleted: true, id: string }

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/cap-table/share-classes/id_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Cap table — Shareholdings

Holdings of a share class by an entity or person. entityId and shareClassId are referentially checked on create; entityId, shareClassId, holderId and holderType are immutable afterwards — a share transfer is a NEW shareholding, mirroring the internal transaction ledger.

GET/api/v1/cap-table/shareholdingsList shareholdings

Lists shareholdings with cursor paging.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
limit	query	integer	Optional	Page size. Default 50, maximum 200; non-numeric or non-positive values fall back to the default.
cursor	query	string	Optional	Opaque cursor from the previous page's nextCursor. Treat as opaque — for keys without restricted_records it is an encrypted token.

Response

200 — { data: Shareholding[], nextCursor: string | null }. Each element: id plus the create fields below, workspaceId and audit stamps.

Errors (5)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/cap-table/shareholdings" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/cap-table/shareholdingsCreate a shareholding

Creates a shareholding. entityId and shareClassId must exist in the key's workspace (422 with per-field messages otherwise). status defaults to "current" so the holding is visible to cap-table builds. Fires shareholding.created.

scope: writemodule: tithe

Request body

Strict object validated by PublicApiShareholdingCreateSchema.

Field	Type	Required	Description
entityId	string	Required	Issuing entity id — must exist in this workspace.
shareClassId	string	Required	Share-class id — must exist in this workspace.
holderId	string	Required	Holder id (entity or person document id).
holderType	string	Required	Which collection holderId references.Allowed: "entity", "person"
shares	number	Required	Share count ≥ 0.
paidUp	boolean	Optional	Paid-up flag.
amountUnpaid	number	Optional	Unpaid amount ≥ 0.
encumbrance	string	Optional	Encumbrance.Allowed: "none", "pledge", "usufruct"
status	string	Optional	Defaults to "current".Allowed: "current", "historic"

Response

201 — The created shareholding record.

Errors (8)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/cap-table/shareholdings" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "entityId": "entity_123",
  "shareClassId": "shareclass_123",
  "holderId": "holder_123",
  "holderType": "entity",
  "shares": 1
}'

GET/api/v1/cap-table/shareholdings/{id}Get a shareholding

Reads one shareholding.

scope: readmodule: tithe

Parameters

Parameter	In	Type	Required	Description
id	path	string	Required	Shareholding document id.

Response

200 — The shareholding record.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/cap-table/shareholdings/id_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/cap-table/shareholdings/{id}Update a shareholding

Merge-patches a shareholding. entityId/shareClassId/holderId/holderType are immutable (unknown key → 422). Fires shareholding.updated.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
id	path	string	Required	Shareholding document id.

Request body

Strict object, at least one field (PublicApiShareholdingPatchSchema).

Field	Type	Required	Description
shares	number	Optional	Share count ≥ 0.
paidUp	boolean	Optional	Paid-up flag.
amountUnpaid	number\| null	Optional	Unpaid amount; null clears.
encumbrance	string\| null	Optional	Encumbrance; null clears.Allowed: "none", "pledge", "usufruct"
status	string	Optional	Holding status.Allowed: "current", "historic"

Response

200 — The merged shareholding record.

Errors (9)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	The body is not a plain JSON object, contains unknown keys, or a field fails its schema; a fields map names each offending field.
413	Request body too large.	The JSON body exceeds 1 MiB (1,048,576 bytes).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/cap-table/shareholdings/id_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "shares": 1
}'

DELETE/api/v1/cap-table/shareholdings/{id}Delete a shareholding

Deletes a shareholding. Fires shareholding.deleted.

scope: writemodule: tithe

Parameters

Parameter	In	Type	Required	Description
id	path	string	Required	Shareholding document id.

Response

200 — { deleted: true, id: string }

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/cap-table/shareholdings/id_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Resource

Webhook subscriptions

Manage outbound webhook subscriptions. Every operation requires the manage_webhooks capability on top of the read/write scope; mutations additionally require the workspace's Enterprise webhook entitlement. A workspace may hold at most 25 subscriptions. The signingSecret is returned exactly once, in the POST response.

GET/api/v1/webhooksList webhook subscriptions

Lists all subscriptions (no paging — the collection is capped at 25).

scope: readcapability: manage_webhooks

Response

200 — { data: WebhookSubscription[] } (no nextCursor). Each element: { id, url, events, recordAccess (open_only | restricted), enabled, createdAt?, updatedAt?, lastDeliveryAt?, lastDeliveryStatus? (success | failure) } — signingSecret is NEVER included after creation.

Errors (6)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
403	Forbidden: manage_webhooks capability required	The key does not carry the manage_webhooks capability.
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/webhooks" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/webhooksCreate a webhook subscription

Registers an HTTPS endpoint. The URL must be public HTTPS (private/loopback/link-local/metadata hosts, credentials, fragments are rejected — SSRF guard), at most 2,048 chars. recordAccess: "restricted" requires the restricted_records capability. The response is the ONLY time signingSecret (whsec_ + 48 hex chars) is revealed.

scope: writecapability: manage_webhooks

Request body

Strict object — only url, events and recordAccess are allowed.

Field	Type	Required	Description
url	string	Required	Public HTTPS endpoint, max 2,048 chars, no credentials or fragment.
events	array<string>	Required	Non-empty array of subscribable event names (see webhooks.events), no duplicates. "ping" cannot be subscribed.
recordAccess	string	Optional	Defaults to "open_only". "restricted" requires the restricted_records capability.Allowed: "open_only", "restricted"

Response

201 — { id, url, events, recordAccess, enabled: true, signingSecret (shown ONCE), createdAt }

Errors (10)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
403	Forbidden: manage_webhooks capability required	The key does not carry the manage_webhooks capability.
403	Outbound webhooks require Enterprise.	The workspace billing document is not an active/trialing Enterprise subscription.
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	Unknown keys, bad URL, unknown/duplicate events, or recordAccess: restricted without the capability — fields map names each.
409	A workspace may have at most 25 webhook subscriptions.	The 25-subscription cap is reached. Body carries limit: 25.
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/webhooks" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/alethia",
  "events": [
    "deal.created",
    "deal.updated"
  ]
}'

GET/api/v1/webhooks/{subId}Get a webhook subscription

Reads one subscription (strict public projection — secrets and internal principals never returned).

scope: readcapability: manage_webhooks

Parameters

Parameter	In	Type	Required	Description
subId	path	string	Required	Subscription id.

Response

200 — { id, url, events, recordAccess (open_only | restricted), enabled, createdAt?, updatedAt?, lastDeliveryAt?, lastDeliveryStatus? (success | failure) } — signingSecret is NEVER included after creation.

Errors (7)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
403	Forbidden: manage_webhooks capability required	The key does not carry the manage_webhooks capability.
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl "https://app.alethiahq.com/api/v1/webhooks/sub_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

PATCH/api/v1/webhooks/{subId}Update a webhook subscription

Strictly permits enabled, url, events and recordAccess; anything else → 422. At least one updatable field must be supplied.

scope: writecapability: manage_webhooks

Parameters

Parameter	In	Type	Required	Description
subId	path	string	Required	Subscription id.

Request body

Strict partial update.

Field	Type	Required	Description
enabled	boolean	Optional	Enable/disable delivery.
url	string	Optional	New public HTTPS endpoint (same validation as create).
events	array<string>	Optional	Replacement event list (same validation as create).
recordAccess	string	Optional	"restricted" requires the restricted_records capability.Allowed: "open_only", "restricted"

Response

200 — The updated subscription projection.

Errors (10)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
403	Forbidden: manage_webhooks capability required	The key does not carry the manage_webhooks capability.
403	Outbound webhooks require Enterprise.	The workspace billing document is not an active/trialing Enterprise subscription.
400	Invalid JSON body.	The request body is not parseable JSON.
422	Validation failed	Unknown keys, no updatable fields, or a field fails validation.
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X PATCH "https://app.alethiahq.com/api/v1/webhooks/sub_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'

DELETE/api/v1/webhooks/{subId}Delete a webhook subscription

Removes the subscription. Deleting immediately frees capacity against the 25-subscription cap.

scope: writecapability: manage_webhooks

Parameters

Parameter	In	Type	Required	Description
subId	path	string	Required	Subscription id.

Response

200 — { deleted: true, id: string }

Errors (7)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
403	Forbidden: manage_webhooks capability required	The key does not carry the manage_webhooks capability.
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X DELETE "https://app.alethiahq.com/api/v1/webhooks/sub_123" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

POST/api/v1/webhooks/{subId}/testSend a test (ping) delivery

Fires a synthetic "ping" event at the subscription's URL, signed with its signingSecret, and reports the outcome. The subscription must be enabled and structurally deliverable. Payload data: { message: "Test delivery from Alethia", subscriptionId }.

scope: writecapability: manage_webhooks

Parameters

Parameter	In	Type	Required	Description
subId	path	string	Required	Subscription id.

Response

200 — { ok: boolean, statusCode: number (0 on network failure), durationMs: number, skipped?: "ssrf" }

Errors (9)

Status	Error	When
401	Unauthorized	Missing, malformed, unknown, revoked, or expired API key (no detail is leaked about which).
403	Forbidden: <reason>	The key lacks the required scope, the workspace subscription is not an active Enterprise plan, workspace access is suspended, or the required module is not on the plan.
429	Rate limit exceeded	More than 1,000 requests in the key's 15-minute window. Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are set.
503	The public API is not configured in this environment.	The deployment has no API_KEY_PEPPER or Firebase Admin credentials (the feature is dormant).
403	Forbidden: manage_webhooks capability required	The key does not carry the manage_webhooks capability.
403	Outbound webhooks require Enterprise.	The workspace billing document is not an active/trialing Enterprise subscription.
404	Not found	No record with this id exists in the key's workspace (restricted records the key cannot access are indistinguishable from absent ones).
409	Webhook subscription is not deliverable.	The stored subscription fails integrity validation (disabled, malformed URL/events/secret, or wrong workspace).
502	Bad Gateway	The datastore read or write failed.

Example request

curl -X POST "https://app.alethiahq.com/api/v1/webhooks/sub_123/test" \
  -H "Authorization: Bearer tk_{workspaceId}_{secret}"

Continue reading

Authentication →Webhooks →Errors & limits →OpenAPI spec →

Questions about a specific integration?

Tell us what you're building and we'll walk through the resources and events that fit.

Request demo