Subjects

Enrolled people and their reference signatures.

The `Subject` object

Attributes

subject_reference required Type: string
created_at required Type: string
references required Type: Reference[]
checks required Type: object
The subject's checks.

The Subject object

{
  "subject_reference": "cust-88",
  "created_at": "2026-09-25T10:15:30.123Z",
  "checks": {
    "recent": [
      {
        "job_id": "inv-2291",
        "index": 0,
        "reference": "APP-1042",
        "process": "loan-application",
        "subject_reference": "cust-88",
        "file": "questioned",
        "input_type": "photo",
        "decision": "APPROVE",
        "match_probability": 0.94,
        "created_at": "2026-09-27T14:22:05.120Z"
      }
    ],
    "total": 1,
    "next": "/nib/checks?view=items&subject_reference=cust-88"
  },
  "references": [
    {
      "ref_id": "card-2019",
      "ref": "ref_01j9x3m8v7k2q4r5s6t7u8v9w1",
      "source": "signature_card",
      "anchor": true,
      "learned_from": null,
      "confirmed_by": null,
      "content_hash": "sha256:070a8e98f85afe04ba05542428664ec3684db24bc356133c11d41f9fab27f135",
      "quality": {
        "ok": true
      },
      "versions": {
        "model": "nib-2.6"
      },
      "created_at": "2026-09-25T10:15:30.123Z",
      "unlearned_at": null
    }
  ]
}

The `Reference` object

Attributes

ref_id required Type: string
ref required Type: string
source required Type: "signature_card" "confirmed_past" "unverified" "learned"
anchor required Type: boolean
Enrolled by you; never replaced by learned ones.
learned_from required Type: string null
The source check, <job_id>/<index>.
confirmed_by required Type: string null
content_hash required Type: string null
quality required Type: object null
versions required Type: object
The model version at enrolment.
created_at required Type: string
unlearned_at required Type: string null

Reference on its own page

List subjects

GET /nib/subjects

Needs nib:subjects:read: Read subjects/references metadata and thumbnails

With reference counts and last check, newest first.

Parameters

cursor queryoptional Type: string
The previous page's next_cursor.
limit queryoptional Type: integer
q queryoptional Type: string
Subject reference prefix.

Returns

200 Type: SubjectList
A page of subjects
400 Type: Problem
invalid_request, invalid_version, idempotency_key_required or invalid_signature
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

GET /nib/subjects · curl

curl "https://api.unforged.sh/nib/subjects" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

GET /nib/subjects · Python

import requests

r = requests.get(
    "https://api.unforged.sh/nib/subjects",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

GET /nib/subjects · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());

Response 200

{
  "subjects": [
    {
      "subject_reference": "cust-88",
      "created_at": "2026-09-25T10:15:30.123Z",
      "last_checked_at": "2026-09-27T14:22:05.120Z",
      "references": {
        "total": 3,
        "anchors": 2,
        "learned": 1
      }
    }
  ],
  "next_cursor": null
}

A subject and its references

GET /nib/subjects/{subject_reference}

Needs nib:subjects:read: Read subjects/references metadata and thumbnails

Includes its 25 newest checked items (checks.recent).

Parameters

subject_reference pathrequired Type: Id
Your id for the person.

Returns

200 Type: Subject
The subject
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

GET /nib/subjects/{subject_reference} · curl

curl "https://api.unforged.sh/nib/subjects/{subject_reference}" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

GET /nib/subjects/{subject_reference} · Python

import requests

r = requests.get(
    "https://api.unforged.sh/nib/subjects/{subject_reference}",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

GET /nib/subjects/{subject_reference} · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());

Response 200

{
  "subject_reference": "cust-88",
  "created_at": "2026-09-25T10:15:30.123Z",
  "checks": {
    "recent": [
      {
        "job_id": "inv-2291",
        "index": 0,
        "reference": "APP-1042",
        "process": "loan-application",
        "subject_reference": "cust-88",
        "file": "questioned",
        "input_type": "photo",
        "decision": "APPROVE",
        "match_probability": 0.94,
        "created_at": "2026-09-27T14:22:05.120Z"
      }
    ],
    "total": 1,
    "next": "/nib/checks?view=items&subject_reference=cust-88"
  },
  "references": [
    {
      "ref_id": "card-2019",
      "ref": "ref_01j9x3m8v7k2q4r5s6t7u8v9w1",
      "source": "signature_card",
      "anchor": true,
      "learned_from": null,
      "confirmed_by": null,
      "content_hash": "sha256:070a8e98f85afe04ba05542428664ec3684db24bc356133c11d41f9fab27f135",
      "quality": {
        "ok": true
      },
      "versions": {
        "model": "nib-2.6"
      },
      "created_at": "2026-09-25T10:15:30.123Z",
      "unlearned_at": null
    }
  ]
}

Permanently delete a subject and its references

DELETE /nib/subjects/{subject_reference}

Needs nib:references:delete: Delete references and subjects, unlearn

Also revokes the subject's sessions.

Parameters

subject_reference pathrequired Type: Id
Your id for the person.

Returns

204
Done
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

DELETE /nib/subjects/{subject_reference} · curl

curl -X DELETE "https://api.unforged.sh/nib/subjects/{subject_reference}" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

DELETE /nib/subjects/{subject_reference} · Python

import requests

r = requests.delete(
    "https://api.unforged.sh/nib/subjects/{subject_reference}",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

DELETE /nib/subjects/{subject_reference} · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());

Enrol reference signatures

PUT /nib/subjects/{subject_reference}/references

Needs nib:references:write: Enroll references, confirm-to-learn

Adds references, creating the subject if new: one PNG, JPEG, WebP, BMP, GIF, TIFF or PDF part per ref_id (at most 20 files, 20 MB), or JSON with URLs. Over 3 are queued (202). learned- ids are reserved.

Parameters

subject_reference pathrequired Type: Id
Your id for the person.

Request body

ReferencesByUrl

references required Type: object[]

Returns

200 Type: ReferencesResult
The references enrolled or rejected
202 Type: ReferencesResult
Some references were queued
400 Type: Problem
invalid_request, invalid_version, idempotency_key_required or invalid_signature
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
413 Type: Problem
too_large
415 Type: Problem
unsupported_media
421 Type: Problem
wrong_region
422 Type: Problem
fetch_failed or not_allowlisted
429 Type: Problem
rate_limited or quota_exceeded
503 Type: Problem
busy, not_ready, org_moving or storage_provisioning (your organisation's storage is still being set up); retry after Retry-After
504 Type: Problem
timeout; a check continues asynchronously (job_id, status_url)
default Type: Problem
internal

PUT /nib/subjects/{subject_reference}/references · curl

curl -X PUT "https://api.unforged.sh/nib/subjects/{subject_reference}/references" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{
  "references": [
    {
      "ref_id": "card-2019",
      "url": "https://files.example.com/card.png",
      "source": "signature_card"
    }
  ]
}'

PUT /nib/subjects/{subject_reference}/references · Python

import requests

r = requests.put(
    "https://api.unforged.sh/nib/subjects/{subject_reference}/references",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={
        "references": [
            {
                "ref_id": "card-2019",
                "url": "https://files.example.com/card.png",
                "source": "signature_card"
            }
        ]
    },
)
print(r.json())

PUT /nib/subjects/{subject_reference}/references · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}/references', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "references": [
      {
        "ref_id": "card-2019",
        "url": "https://files.example.com/card.png",
        "source": "signature_card"
      }
    ]
  }),
});
console.log(await res.json());

Response 200

{
  "subject_reference": "cust-88",
  "references": [
    {
      "ref_id": "card-2019",
      "source": "signature_card",
      "status": "enrolled",
      "ref": "ref_01j9x3m8v7k2q4r5s6t7u8v9w1"
    },
    {
      "ref_id": "blurry",
      "source": "unverified",
      "status": "rejected",
      "reason": "quality",
      "detail": "the image is too blurred"
    }
  ]
}

Permanently delete a reference

DELETE /nib/subjects/{subject_reference}/references/{ref_id}

Needs nib:references:delete: Delete references and subjects, unlearn

Learned references are removed with unlearn (409).

Parameters

subject_reference pathrequired Type: Id
Your id for the person.
ref_id pathrequired Type: Id

Returns

204
Done
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
409 Type: Problem
conflict, idempotency_conflict, idempotency_in_progress or idempotency_not_replayable
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

DELETE /nib/subjects/{subject_reference}/references/{ref_id} · curl

curl -X DELETE "https://api.unforged.sh/nib/subjects/{subject_reference}/references/{ref_id}" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

DELETE /nib/subjects/{subject_reference}/references/{ref_id} · Python

import requests

r = requests.delete(
    "https://api.unforged.sh/nib/subjects/{subject_reference}/references/{ref_id}",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

DELETE /nib/subjects/{subject_reference}/references/{ref_id} · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}/references/{ref_id}', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());

A reference signature's thumbnail (PNG)

GET /nib/subjects/{subject_reference}/references/{ref_id}/image

Needs nib:subjects:read: Read subjects/references metadata and thumbnails

Greyscale, first page, at most 512 px. 404 if gone.

Parameters

subject_reference pathrequired Type: Id
Your id for the person.
ref_id pathrequired Type: Id

Returns

200
The thumbnail
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
503 Type: Problem
busy, not_ready, org_moving or storage_provisioning (your organisation's storage is still being set up); retry after Retry-After
default Type: Problem
internal

GET /nib/subjects/{subject_reference}/references/{ref_id}/image · curl

curl "https://api.unforged.sh/nib/subjects/{subject_reference}/references/{ref_id}/image" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

GET /nib/subjects/{subject_reference}/references/{ref_id}/image · Python

import requests

r = requests.get(
    "https://api.unforged.sh/nib/subjects/{subject_reference}/references/{ref_id}/image",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

GET /nib/subjects/{subject_reference}/references/{ref_id}/image · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}/references/{ref_id}/image', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());

Remove learned references

POST /nib/subjects/{subject_reference}/references/unlearn

Needs nib:references:delete: Delete references and subjects, unlearn

By since or source check; those checks are never learned again.

Parameters

subject_reference pathrequired Type: Id
Your id for the person.
Idempotency-Key headerrequired Type: string
1–255 printable ASCII characters, kept 24 hours.

Request body

UnlearnRequest

Returns

200 Type: Unlearned
The references removed (possibly none)
400 Type: Problem
invalid_request, invalid_version, idempotency_key_required or invalid_signature
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
409 Type: Problem
conflict, idempotency_conflict, idempotency_in_progress or idempotency_not_replayable
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

POST /nib/subjects/{subject_reference}/references/unlearn · curl

curl -X POST "https://api.unforged.sh/nib/subjects/{subject_reference}/references/unlearn" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{
  "since": "2026-09-01T00:00:00Z"
}'

POST /nib/subjects/{subject_reference}/references/unlearn · Python

import requests

r = requests.post(
    "https://api.unforged.sh/nib/subjects/{subject_reference}/references/unlearn",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={
        "since": "2026-09-01T00:00:00Z"
    },
)
print(r.json())

POST /nib/subjects/{subject_reference}/references/unlearn · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}/references/unlearn', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "since": "2026-09-01T00:00:00Z"
  }),
});
console.log(await res.json());

Response 200

{
  "subject_reference": "cust-88",
  "unlearned": [
    "learned-01j9x3m8v7k2q4r5s6t7u8v9w0"
  ]
}

Delete the reference whose ref_id is `unlearn`

DELETE /nib/subjects/{subject_reference}/references/unlearn

Needs nib:references:delete: Delete references and subjects, unlearn

DELETE …/references/{ref_id} for the ref_id unlearn.

Parameters

subject_reference pathrequired Type: Id
Your id for the person.

Returns

204
Done
401 Type: Problem
unauthorized
403 Type: Problem
permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
404 Type: Problem
not_found
421 Type: Problem
wrong_region
429 Type: Problem
rate_limited or quota_exceeded
default Type: Problem
internal

DELETE /nib/subjects/{subject_reference}/references/unlearn · curl

curl -X DELETE "https://api.unforged.sh/nib/subjects/{subject_reference}/references/unlearn" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"

DELETE /nib/subjects/{subject_reference}/references/unlearn · Python

import requests

r = requests.delete(
    "https://api.unforged.sh/nib/subjects/{subject_reference}/references/unlearn",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())

DELETE /nib/subjects/{subject_reference}/references/unlearn · Node.js

const res = await fetch('https://api.unforged.sh/nib/subjects/{subject_reference}/references/unlearn', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());

The Subject object

Attributes

The Reference object

Attributes

List subjects

Parameters

Returns

A subject and its references

Parameters

Returns

Permanently delete a subject and its references

Parameters

Returns

Enrol reference signatures

Parameters

Request body

Returns

Permanently delete a reference

Parameters

Returns

A reference signature's thumbnail (PNG)

Parameters

Returns

Remove learned references

Parameters

Request body

Returns

Delete the reference whose ref_id is `unlearn`

Parameters

Returns

The `Subject` object

The `Reference` object