Docs/Project Data

Project Data

These endpoints let API key owners and project members read aggregate stats and lists of sessions and uploads across the projects they have access to. They are designed for the dashboard and internal tooling, not for end-user clients.

Authentication

All project-data endpoints accept two authentication modes. Pass a dashboard JWT as a Bearer token to query across every project you own or belong to, or pass an API key (Bearer aptr_…) to scope the results to that key's project.

Recent sessions

Returns the most recently created upload sessions across every project the caller has access to. Useful for dashboard activity feeds.

GET/api/v1/sessions/recent

Query parameters

Field	Type	Required	Description
limit	integer	No	Number of records to return. Defaults to 10, maximum 50.

Response

Returns an array of session row objects (no pagination wrapper).

Field	Type	Description
id	string	Session UUID.
createdAt	string	ISO 8601 datetime when the session was created.
expiresAt	string	ISO 8601 datetime when the session expires.
status	string	One of pending, active, expired, completed, failed.
projectId	string	UUID of the project this session belongs to.
projectName	string	Display name of the project.
imagesCount	integer	Total number of upload records on this session.
imagesDelivered	integer	Number of uploads with at least one successful delivery.
imagesFailed	integer	Number of uploads where any destination failed.
destinationsCount	integer	Number of destinations the session is fanning out to.
tags	string[] \| null	Session tags, or null if none were set.
longPollingEnabled	boolean	Whether long polling is enabled for this session.

curl https://api.apertur.ca/api/v1/sessions/recent?limit=10 \
  -H "Authorization: Bearer <jwt-token>"

List sessions

Paginated list of upload sessions across every project the caller has access to.

GET/api/v1/sessions

Query parameters

Field	Type	Required	Description
page	integer	No	Page number to return. Defaults to 1.
pageSize	integer	No	Number of records per page. Defaults to 20, maximum 100.

Response

Returns a paginated wrapper. The data array contains session row objects with the same shape as /sessions/recent.

{
  "data": [/* array of session row objects */],
  "total": 134,
  "page": 1,
  "pageSize": 20,
  "totalPages": 7
}

Field	Type	Description
id	string	Session UUID.
createdAt	string	ISO 8601 datetime when the session was created.
expiresAt	string	ISO 8601 datetime when the session expires.
status	string	One of pending, active, expired, completed, failed.
projectId	string	UUID of the project this session belongs to.
projectName	string	Display name of the project.
imagesCount	integer	Total number of upload records on this session.
imagesDelivered	integer	Number of uploads with at least one successful delivery.
imagesFailed	integer	Number of uploads where any destination failed.
destinationsCount	integer	Number of destinations the session is fanning out to.
tags	string[] \| null	Session tags, or null if none were set.
longPollingEnabled	boolean	Whether long polling is enabled for this session.

curl "https://api.apertur.ca/api/v1/sessions?page=1&pageSize=20" \
  -H "Authorization: Bearer <jwt-token>"

Recent uploads

Returns the most recently received upload records across every project the caller has access to, with per-destination delivery counts.

GET/api/v1/uploads/recent

Query parameters

Field	Type	Required	Description
limit	integer	No	Number of records to return. Defaults to 10, maximum 50.

Response

Returns an array of upload row objects (no pagination wrapper).

Field	Type	Description
id	string	Upload record UUID.
filename	string	Original filename of the uploaded file.
sizeBytes	integer	File size in bytes.
mimeType	string	Detected MIME type of the upload.
source	string	One of camera, gallery, url, google_drive, google_photos, dropbox, onedrive, box, instagram.
isEncrypted	boolean	Whether the file is stored client-side encrypted.
createdAt	string	ISO 8601 datetime when the upload was received.
sessionId	string	UUID of the parent upload session.
projectId	string	UUID of the project this upload belongs to.
projectName	string	Display name of the project.
destinationsTotal	integer	Total number of destinations this upload is being delivered to.
destinationsDelivered	integer	Number of destinations that have successfully received the upload.
destinationsFailed	integer	Number of destinations that have permanently failed.
destinationsBreakdown	object[]	Array of { type, count } objects grouping delivery results by destination type.
status	string	Derived status: delivered, failed, partial, pending, or stored_only. See note below.

Upload status derivation

delivered = all destinations sent successfully. failed = at least one destination has finished and all of them failed. partial = mixed delivered and failed. pending = some destinations have not reported yet. stored_only = no destinations were dispatched (the image is stored on the server only).

curl https://api.apertur.ca/api/v1/uploads/recent?limit=10 \
  -H "Authorization: Bearer <jwt-token>"

List uploads

Paginated list of upload records across every project the caller has access to.

GET/api/v1/uploads

Query parameters

Field	Type	Required	Description
page	integer	No	Page number to return. Defaults to 1.
pageSize	integer	No	Number of records per page. Defaults to 20, maximum 100.

Response

Returns a paginated wrapper. The data array contains upload row objects with the same shape as /uploads/recent.

{
  "data": [/* array of upload row objects */],
  "total": 482,
  "page": 1,
  "pageSize": 20,
  "totalPages": 25
}

Field	Type	Description
id	string	Upload record UUID.
filename	string	Original filename of the uploaded file.
sizeBytes	integer	File size in bytes.
mimeType	string	Detected MIME type of the upload.
source	string	One of camera, gallery, url, google_drive, google_photos, dropbox, onedrive, box, instagram.
isEncrypted	boolean	Whether the file is stored client-side encrypted.
createdAt	string	ISO 8601 datetime when the upload was received.
sessionId	string	UUID of the parent upload session.
projectId	string	UUID of the project this upload belongs to.
projectName	string	Display name of the project.
destinationsTotal	integer	Total number of destinations this upload is being delivered to.
destinationsDelivered	integer	Number of destinations that have successfully received the upload.
destinationsFailed	integer	Number of destinations that have permanently failed.
destinationsBreakdown	object[]	Array of { type, count } objects grouping delivery results by destination type.
status	string	Derived status: delivered, failed, partial, pending, or stored_only. See note below.

curl "https://api.apertur.ca/api/v1/uploads?page=1&pageSize=20" \
  -H "Authorization: Bearer <jwt-token>"

Aggregate stats

Returns aggregate metrics across all projects the caller has access to, including this-month counts and the top projects by activity.

GET/api/v1/stats

Response

Field	Type	Description
sessionsThisMonth	integer	Number of sessions created this calendar month.
sessionsTotal	integer	All-time total number of sessions.
imagesUploaded	integer	All-time total number of uploaded records.
imagesDelivered	integer	Number of upload records with at least one successful delivery.
deliverySuccessRate	integer	Percentage 0–100, computed from per-destination sent / (sent + failed).
totalProjects	integer	Total number of projects the caller has access to.
activeKeys	integer	Number of API keys currently active across those projects.
topProjects	object[]	Array of up to 10 { id, name, sessions } objects ranked by session count this month.

curl https://api.apertur.ca/api/v1/stats \
  -H "Authorization: Bearer <jwt-token>"

← Upload Sessions Next: Destinations →