API reference

Records

Every path is under https://impartire.com/api/v1. Generated from the API’s own contract, openapi.json (OpenAPI 3.1), which you can load into any OpenAPI tool. Errors are Problems — see Conventions.

GET/api/v1/records

List one record type's records

type_id is required: records are listed one type at a time. Newest first unless sort says otherwise. To poll for changes, pass updated_after with the newest updated_at you have seen and sort=-updated_at (or updated_at); a deleted record leaves the list. Each record carries its fields and its references resolved to names. For an OAuth token, records its person may not read are left out (a page may be short and still have a next one) and the fields they may not read are stripped. All 404 when the org does not have custom records.

Scopes: records:read

Parameters

type_idquery · string (uuid)required
Required: the record type whose records to list (GET /api/v1/record-types).
qquery · string
Case-insensitive substring of the record's title. Characters are matched literally.
project_idquery · string (uuid)
Only records filed under this project (GET /api/v1/projects).
updated_afterquery · string (date-time)
Only records changed strictly after this instant (ISO 8601 with offset), compared to the millisecond — pass the newest updated_at you have seen and that record is not returned again.
sortquery · "created_at" | "-created_at" | "title" | "-title" | "updated_at" | "-updated_at"
Sort key; a leading - is descending. Default -created_at (newest first, as the app lists them). Ties break on id.
limitquery · integer
Page size, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page, with the other parameters unchanged.

Response 200RecordList

dataarray of Recordrequired
- idstring (uuid)required
- typeobjectrequired
  Its record type (GET /api/v1/record-types).
  - idstring (uuid)required
  - namestringrequired
- titlestringrequired
- fieldsobject (any keys)required
  Field values keyed by field key, as defined by the record type. For an OAuth token, the fields its person may not read are left out.
- referencesarray of RecordReferencerequired
  Every value of the reference fields in fields, resolved to a name, in the type's field order then value order.
  - field_keystringrequired
    The reference field the value is stored under in fields.
  - recordobject or nullrequired
    Set when the field points at a record.
    - idstring (uuid)required
    - namestring or nullrequired
      The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
  - assetobject or nullrequired
    Set when the field points at an asset (by the id stored in fields).
    - idstring (uuid)required
    - namestring or nullrequired
      The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
  - projectobject or nullrequired
    Set when the field points at a project.
    - idstring (uuid)required
    - namestring or nullrequired
      The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- projectProjectRef or nullrequired
  A project the record is filed under, or null. Informational: records are org-wide, and who may read one does not depend on it.
  - idstring (uuid)required
  - namestringrequired
- edit_seqintegerrequired
  Increments on every change to title, fields, type or project. The first part of the ETag; If-Match on PATCH compares it.
- created_atstring (date-time)required
- updated_atstring (date-time)required
next_cursorstring or nullrequired
Pass as cursor to get the next page; null means this is the last page. For an OAuth token a page may hold fewer than limit records (those its person may not read are left out) and still have a next page.

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
422 validation — a missing or unknown type_id (an asset type's id included), an unknown project_id, or a bad limit, updated_after, sort or cursor.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

POST/api/v1/records

Create a record

fields is validated against the record type (GET /record-types): a reference field holds the target's id (an array when multiple) — a live asset, a record of the declared type, or a project of the org. Its reference edges are written with the record. project_id files it under a project; it does not change who may read it (records are org-wide). An OAuth token's person needs create_asset in the org (the app's permission for records), and may not send a field they cannot read. All 404 when the org does not have custom records.

Scopes: records:write

Parameters

Idempotency-Keyheader · string
Makes a retry safe: the same key and request within 24 hours replays the first response. 1–255 characters.

Request bodyCreateRecordRequest

type_idstring (uuid)required
A record type from GET /api/v1/record-types.
titlestringrequired
Leading and trailing spaces are trimmed; it may not be blank.
fieldsobject (any keys)
Field values keyed by field key, validated against the record type (a reference: the target's id, or an array of ids when multiple).
project_idstring (uuid)
File the record under this project (GET /api/v1/projects). Informational: it does not change who may read it.

Response 201Record

An instance of a record type: a title, a field bag and resolved references.

idstring (uuid)required
typeobjectrequired
Its record type (GET /api/v1/record-types).
- idstring (uuid)required
- namestringrequired
titlestringrequired
fieldsobject (any keys)required
Field values keyed by field key, as defined by the record type. For an OAuth token, the fields its person may not read are left out.
referencesarray of RecordReferencerequired
Every value of the reference fields in fields, resolved to a name, in the type's field order then value order.
- field_keystringrequired
  The reference field the value is stored under in fields.
- recordobject or nullrequired
  Set when the field points at a record.
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- assetobject or nullrequired
  Set when the field points at an asset (by the id stored in fields).
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- projectobject or nullrequired
  Set when the field points at a project.
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
projectProjectRef or nullrequired
A project the record is filed under, or null. Informational: records are org-wide, and who may read one does not depend on it.
- idstring (uuid)required
- namestringrequired
edit_seqintegerrequired
Increments on every change to title, fields, type or project. The first part of the ETag; If-Match on PATCH compares it.
created_atstring (date-time)required
updated_atstring (date-time)required

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may not create records, or sent a field they cannot read.
404 not-found.
409 idempotency-in-flight.
422 validation (type_id, title, project_id, or fields.<key> naming each invalid value), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 authorization-write-failed — the record's permissions could not be written, so it was rolled back; or internal.

GET/api/v1/records/{id}

Get one record

Scopes: records:read

Parameters

idpath · string (uuid)required
The record's id, from GET /api/v1/records?type_id=.
If-None-Matchheader · string
An ETag from a previous response; 304 if unchanged.

Response 200Record

An instance of a record type: a title, a field bag and resolved references.

idstring (uuid)required
typeobjectrequired
Its record type (GET /api/v1/record-types).
- idstring (uuid)required
- namestringrequired
titlestringrequired
fieldsobject (any keys)required
Field values keyed by field key, as defined by the record type. For an OAuth token, the fields its person may not read are left out.
referencesarray of RecordReferencerequired
Every value of the reference fields in fields, resolved to a name, in the type's field order then value order.
- field_keystringrequired
  The reference field the value is stored under in fields.
- recordobject or nullrequired
  Set when the field points at a record.
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- assetobject or nullrequired
  Set when the field points at an asset (by the id stored in fields).
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- projectobject or nullrequired
  Set when the field points at a project.
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
projectProjectRef or nullrequired
A project the record is filed under, or null. Informational: records are org-wide, and who may read one does not depend on it.
- idstring (uuid)required
- namestringrequired
edit_seqintegerrequired
Increments on every change to title, fields, type or project. The first part of the ETag; If-Match on PATCH compares it.
created_atstring (date-time)required
updated_atstring (date-time)required

Other responses

304 Not modified — the ETag in If-None-Match is current.
401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope — the key lacks a required scope.
404 not-found.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

PATCH/api/v1/records/{id}

Retitle a record or replace its fields

If-Match is required: the ETag from the last GET (or the create), or the bare edit_seq. fields replaces the whole bag (send back what GET returned, changed) and the reference edges follow it. An unknown field (type_id, project_id) is a 422. An OAuth token's person needs edit on the record; a field they cannot read is kept as it was and may not be sent. All 404 when the org does not have custom records.

Scopes: records:write

Parameters

idpath · string (uuid)required
The record's id, from GET /api/v1/records?type_id=.
If-Matchheader · stringrequired
The record's ETag, or its bare edit_seq.

Request bodyUpdateRecordRequest

At least one of title, fields. Changing a record's type or project is not in v1; an unknown field is a 422.

titlestring
Leading and trailing spaces are trimmed; it may not be blank.
fieldsobject (any keys)
The record's whole field bag, validated against its type: keys left out are removed (send back what GET returned, changed). Legacy <key>__legacy values are carried forward unless sent as null. For an OAuth token, a field its person may not read is kept as it was.

Response 200Record

An instance of a record type: a title, a field bag and resolved references.

idstring (uuid)required
typeobjectrequired
Its record type (GET /api/v1/record-types).
- idstring (uuid)required
- namestringrequired
titlestringrequired
fieldsobject (any keys)required
Field values keyed by field key, as defined by the record type. For an OAuth token, the fields its person may not read are left out.
referencesarray of RecordReferencerequired
Every value of the reference fields in fields, resolved to a name, in the type's field order then value order.
- field_keystringrequired
  The reference field the value is stored under in fields.
- recordobject or nullrequired
  Set when the field points at a record.
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- assetobject or nullrequired
  Set when the field points at an asset (by the id stored in fields).
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
- projectobject or nullrequired
  Set when the field points at a project.
  - idstring (uuid)required
  - namestring or nullrequired
    The target's name (a record's title; a sub-project's as <parent> › <name> when the parent is readable too). Null when the target is gone or — for an OAuth token — its person may not read it: the id is already in fields, the name is not disclosed.
projectProjectRef or nullrequired
A project the record is filed under, or null. Informational: records are org-wide, and who may read one does not depend on it.
- idstring (uuid)required
- namestringrequired
edit_seqintegerrequired
Increments on every change to title, fields, type or project. The first part of the ETag; If-Match on PATCH compares it.
created_atstring (date-time)required
updated_atstring (date-time)required

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may read the record but not edit it, or sent a field they cannot read.
404 not-found.
412 precondition-failed — If-Match is stale; edit_seq in the body is the current one.
422 validation (empty body, an unknown field, title, or fields.<key> naming each invalid value).
428 precondition-required — no If-Match.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

DELETE/api/v1/records/{id}

Delete a record

Soft-deletes the record; it no longer appears in reads, lists or referenced-by. No If-Match: a second DELETE is a 404. An OAuth token's person needs delete on the record. All 404 when the org does not have custom records.

Scopes: records:write

Parameters

idpath · string (uuid)required
The record's id, from GET /api/v1/records?type_id=.

Other responses

204 Deleted.
401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may read the record but not delete it.
404 not-found.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.