API reference

List projects

List projects owned by the API key. Review Diffio API behavior, response fields, setup details, and production workflows.

List projects owned by the API key.

POST/v1/list_projectsPermissions: read

Endpoint

HTTP request

https://api.diffio.ai/v1/list_projects

Use POST with a JSON body.

Permissions

read

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Send a JSON object to list projects for the API key. Additional fields are ignored.

This endpoint expects an empty JSON object.

cURL

curl -X POST "https://api.diffio.ai/v1/list_projects" \  -H "Authorization: Bearer $DIFFIO_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Response

Returns a list of projects owned by the API key.

Response fields

Field	Type	Required	Description
`projects`	array	Yes	List of project objects.
`projects[].apiProjectId`	string	Yes	Project identifier.
`projects[].status`	string	Yes	Current project status.
`projects[].originalFileName`	string	Yes	Original file name from the upload.
`projects[].contentType`	string	Yes	MIME type for the uploaded file.
`projects[].hasVideo`	boolean	Yes	True when the project includes video.
`projects[].generationCount`	number	Yes	Count of generations stored for the project.
`projects[].createdAt`	string	Yes	Creation timestamp in ISO 8601 format.
`projects[].updatedAt`	string	Yes	Last updated timestamp in ISO 8601 format.

Successful response

{  "projects": [    {      "apiProjectId": "proj-123",      "status": "uploaded",      "originalFileName": "song.wav",      "contentType": "audio/wav",      "hasVideo": false,      "generationCount": 2,      "createdAt": "2025-01-05T12:34:56Z",      "updatedAt": "2025-01-05T12:35:10Z"    }  ]}

Return codes

200Success, treated as complete.: Project list returned.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: API key is not active, or missing read permission.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Failed to load API projects.

Notes

Returns only projects owned by the API key.
Results are sorted by createdAt in descending order, updatedAt is used when createdAt is missing.
generationCount reflects the size of the project generations list.
hasVideo is derived from stored metadata and file type.