Collectoh
EN

This page is in English only for now. The main pages follow your choice.

Sign up free
Browse the docs

API reference

Faces

Faces found in photos by a local model, gathered to be named (P6-14).

Paths are relative to /api/v1 on your server.

DELETE/faces#

Delete all face data

Every face found, every cluster and every credit made from them, the people who were only ever a name for faces, and the faces cut out for tiles; and face recognition switched off in every library that had it, so nothing is looked for again until someone switches it back on.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/faces/{id}/image#

A face, cut out of its photo

Square, 160 pixels, WebP; to whoever may see the photo. It never changes: a photo looked at again has new faces.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. image/webp ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
PUT/faces/{id}/person#

Say who one face is, or who it is not

A person or a name puts the face with them, in a cluster of its own that faces like it will join. { personId: null } takes it out of every cluster: it is nobody’s, and draws no one’s photos to it, until someone says who it is.

Authorisation
Bearer token or API key · Session cookie
Body
application/json ·
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/faces/clusters/{id}#

One cluster’s faces

The faces of the cluster in photos the caller may see, the clearest first. 404 when that is none.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
limitqueryinteger
offsetqueryinteger
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/faces/clusters/{id}/hide#

Put a cluster away from the ones to name

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/faces/clusters/{id}/name#

Say who a cluster’s faces are

Someone already on this server (personId) or a name (name): a name that is already someone’s is them, since a name is one person here. Every photo with one of its faces is then credited to them (role pictured), and every cluster without a name that comes near enough theirs, and clearly nearer them than anyone else, is named with it (joined).

Authorisation
Bearer token or API key · Session cookie
Body
application/json ·
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/faces/clusters/{id}/unhide#

Bring a cluster back to the ones to name

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
POST/faces/clusters/{id}/unname#

Say a named cluster is not who it was named

Its faces are nobody again and its photos lose their credits for that person; the cluster never follows them again.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks item:edit, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/items/{id}/faces#

The faces in a photo

Left to right, each with where it is (as fractions of the upright picture), its cluster, and who it is once named.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/libraries/{id}/faces#

A photo library’s people

Everyone named in the library’s photos the caller may see, the most photographed first, with a face for each; then the clusters of faces that look alike and have no name yet, the biggest first (hidden=true for the ones put away). A cluster needs two faces to be listed.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
limitqueryinteger
offsetqueryinteger
hiddenquery
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
GET/people/{id}/photos#

Where a person is pictured

The photo libraries with photos of them the caller may see, the most first: the ways to their album there. photosOnly when a name given to faces is all this server knows of them — no catalogue is asked about them, and there is no filmography.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope