Albums

Collections of media, either curated by hand or defined by a saved filter.

List albums

GET

https://api.genuineai.app/api/v1

/albums

Returns albums with a cover preview, how many files each holds and how many child albums it has. A smart album carries the saved search it resolves in album_query_search.

List albums › query Parameters

album_active

boolean

album_created

array

album_description

string

album_id

string · uuid

album_name

string

album_parent

string

album_updated

array

cursor

string · maxLength: 512 · pattern: ^[A-Za-z0-9_-]+$

full_text_search

string

limit

integer

offset

integer · min: 0

sort

string · minLength: 1 · maxLength: 64 · pattern: ^-?[a-z0-9_]+$

List albums › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

List albums › Responses

Success

No data returned

Create an album

POST

https://api.genuineai.app/api/v1

/albums

Creates a curated album, which starts empty — add files to it with POST /albums/{id}/files. An album that fills itself from a saved filter is created through POST /albums/smart instead.

Create an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Create an album › Request Body

album_name

string · minLength: 1 · required

album_description

string

album_cover_file

string · uuid

album_metadata

object

album_acl

object

album_active

boolean

album_smart

boolean

album_query

string · uuid

album_parent

string

Create an album › Responses

Created

No data returned

POST/albums

curl https://api.genuineai.app/api/v1/albums \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <string>' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_active": true,
  "album_smart": true,
  "album_query": "00000000-0000-0000-0000-000000000000",
  "album_parent": "album_parent"
}'

Example Request Body

{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_active": true,
  "album_smart": true,
  "album_query": "00000000-0000-0000-0000-000000000000",
  "album_parent": "album_parent"
}

json

Example Responses

No example specified for this content type

Get an album

GET

https://api.genuineai.app/api/v1

/albums/{id}

Returns the album with its resolved cover, its file and child counts, and — for a smart album — the filter it resolves.

Get an album › path Parameters

id

string · uuid · required

Get an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get an album › Responses

Success

No data returned

Delete an album

DELETE

https://api.genuineai.app/api/v1

/albums/{id}

Removes the album. The files it held stay in the library.

Delete an album › path Parameters

id

string · uuid · required

Delete an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Delete an album › Responses

Success. No content.

No data returned

Update an album

PATCH

https://api.genuineai.app/api/v1

/albums/{id}

Applies the album_-prefixed fields present in the body. A smart album's filter is changed through PATCH /albums/{id}/smart, not here.

Update an album › path Parameters

id

string · uuid · required

Update an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Update an album › Request Body optional

album_name

string · minLength: 1

album_description

string

album_cover_file

string · uuid

album_metadata

object

album_acl

object

album_parent

string

Update an album › Responses

Success

No data returned

PATCH/albums/{id}

curl https://api.genuineai.app/api/v1/albums/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <string>' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_parent": "album_parent"
}'

Example Request Body

{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_parent": "album_parent"
}

json

Example Responses

No example specified for this content type

Add files

POST

https://api.genuineai.app/api/v1

/albums/{id}/files

Adds files to a curated album. Ids that match no file are skipped rather than failing the request, so a partly stale selection still lands.

Add files › path Parameters

id

string · uuid · required

Add files › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Add files › Request Body

file_ids

string[] · required

Add files › Responses

Success

No data returned

Remove files

DELETE

https://api.genuineai.app/api/v1

/albums/{id}/files

Takes the files out of the album and leaves them in the library.

Remove files › path Parameters

id

string · uuid · required

Remove files › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Remove files › Request Body

file_ids

string[] · required

Remove files › Responses

Success

No data returned

Update smart filters

PATCH

https://api.genuineai.app/api/v1

/albums/{id}/smart

Replaces the saved filter a smart album resolves. Membership is recomputed on read, so the change is visible immediately and no files are moved.

Update smart filters › path Parameters

id

string · uuid · required

Update smart filters › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Update smart filters › Request Body optional

album_name

string · minLength: 1

album_description

string

query_search

object

Update smart filters › Responses

Success

No data returned

List album membership

GET

https://api.genuineai.app/api/v1

/albums/memberships

Returns which files belong to which album, without the file records themselves.

List album membership › query Parameters

af_album

string · uuid

af_file

string

cursor

string · maxLength: 512 · pattern: ^[A-Za-z0-9_-]+$

limit

integer

offset

integer · min: 0

sort

string · minLength: 1 · maxLength: 64 · pattern: ^-?[a-z0-9_]+$

List album membership › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

List album membership › Responses

Success

No data returned

Create a smart album

POST

https://api.genuineai.app/api/v1

/albums/smart

A smart album is a saved filter rather than a fixed list: its contents are whatever currently matches, so files join and leave it on their own as the library changes.

Create a smart album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Create a smart album › Request Body

album_name

string · minLength: 1 · required

query_search

object · required

album_description

string

Create a smart album › Responses

Created

No data returned

Get album statistics

GET

https://api.genuineai.app/api/v1

/albums/stats

How many albums the workspace has. For counts within one album, read the album itself — it carries its own file and child counts.

Get album statistics › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get album statistics › Responses

Success

No data returned

Faces People

GenuineAI API

Albums

Collections of media, either curated by hand or defined by a saved filter.

List albums

GET

https://api.genuineai.app/api/v1

/albums

Returns albums with a cover preview, how many files each holds and how many child albums it has. A smart album carries the saved search it resolves in album_query_search.

List albums › query Parameters

album_active

boolean

album_created

array

album_description

string

album_id

string · uuid

album_name

string

album_parent

string

album_updated

array

cursor

string · maxLength: 512 · pattern: ^[A-Za-z0-9_-]+$

full_text_search

string

limit

integer

offset

integer · min: 0

sort

string · minLength: 1 · maxLength: 64 · pattern: ^-?[a-z0-9_]+$

List albums › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

List albums › Responses

Success

No data returned

Create an album

POST

https://api.genuineai.app/api/v1

/albums

Creates a curated album, which starts empty — add files to it with POST /albums/{id}/files. An album that fills itself from a saved filter is created through POST /albums/smart instead.

Create an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Create an album › Request Body

album_name

string · minLength: 1 · required

album_description

string

album_cover_file

string · uuid

album_metadata

object

album_acl

object

album_active

boolean

album_smart

boolean

album_query

string · uuid

album_parent

string

Create an album › Responses

Created

No data returned

POST/albums

curl https://api.genuineai.app/api/v1/albums \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <string>' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_active": true,
  "album_smart": true,
  "album_query": "00000000-0000-0000-0000-000000000000",
  "album_parent": "album_parent"
}'

Example Request Body

{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_active": true,
  "album_smart": true,
  "album_query": "00000000-0000-0000-0000-000000000000",
  "album_parent": "album_parent"
}

json

Example Responses

No example specified for this content type

Get an album

GET

https://api.genuineai.app/api/v1

/albums/{id}

Returns the album with its resolved cover, its file and child counts, and — for a smart album — the filter it resolves.

Get an album › path Parameters

id

string · uuid · required

Get an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get an album › Responses

Success

No data returned

Delete an album

DELETE

https://api.genuineai.app/api/v1

/albums/{id}

Removes the album. The files it held stay in the library.

Delete an album › path Parameters

id

string · uuid · required

Delete an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Delete an album › Responses

Success. No content.

No data returned

Update an album

PATCH

https://api.genuineai.app/api/v1

/albums/{id}

Applies the album_-prefixed fields present in the body. A smart album's filter is changed through PATCH /albums/{id}/smart, not here.

Update an album › path Parameters

id

string · uuid · required

Update an album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Update an album › Request Body optional

album_name

string · minLength: 1

album_description

string

album_cover_file

string · uuid

album_metadata

object

album_acl

object

album_parent

string

Update an album › Responses

Success

No data returned

PATCH/albums/{id}

curl https://api.genuineai.app/api/v1/albums/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <string>' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_parent": "album_parent"
}'

Example Request Body

{
  "album_name": "album_name",
  "album_description": "album_description",
  "album_cover_file": "00000000-0000-0000-0000-000000000000",
  "album_metadata": {},
  "album_acl": {},
  "album_parent": "album_parent"
}

json

Example Responses

No example specified for this content type

Add files

POST

https://api.genuineai.app/api/v1

/albums/{id}/files

Adds files to a curated album. Ids that match no file are skipped rather than failing the request, so a partly stale selection still lands.

Add files › path Parameters

id

string · uuid · required

Add files › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Add files › Request Body

file_ids

string[] · required

Add files › Responses

Success

No data returned

Remove files

DELETE

https://api.genuineai.app/api/v1

/albums/{id}/files

Takes the files out of the album and leaves them in the library.

Remove files › path Parameters

id

string · uuid · required

Remove files › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Remove files › Request Body

file_ids

string[] · required

Remove files › Responses

Success

No data returned

Update smart filters

PATCH

https://api.genuineai.app/api/v1

/albums/{id}/smart

Replaces the saved filter a smart album resolves. Membership is recomputed on read, so the change is visible immediately and no files are moved.

Update smart filters › path Parameters

id

string · uuid · required

Update smart filters › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Update smart filters › Request Body optional

album_name

string · minLength: 1

album_description

string

query_search

object

Update smart filters › Responses

Success

No data returned

List album membership

GET

https://api.genuineai.app/api/v1

/albums/memberships

Returns which files belong to which album, without the file records themselves.

List album membership › query Parameters

af_album

string · uuid

af_file

string

cursor

string · maxLength: 512 · pattern: ^[A-Za-z0-9_-]+$

limit

integer

offset

integer · min: 0

sort

string · minLength: 1 · maxLength: 64 · pattern: ^-?[a-z0-9_]+$

List album membership › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

List album membership › Responses

Success

No data returned

Create a smart album

POST

https://api.genuineai.app/api/v1

/albums/smart

A smart album is a saved filter rather than a fixed list: its contents are whatever currently matches, so files join and leave it on their own as the library changes.

Create a smart album › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Create a smart album › Request Body

album_name

string · minLength: 1 · required

query_search

object · required

album_description

string

Create a smart album › Responses

Created

No data returned

Get album statistics

GET

https://api.genuineai.app/api/v1

/albums/stats

How many albums the workspace has. For counts within one album, read the album itself — it carries its own file and child counts.

Get album statistics › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get album statistics › Responses

Success

No data returned

Faces People