List and search projects

GET/projects

Sample request

cURL

curl -X GET "https://api.abyssale.com/projects" \
  -H "x-api-key: $ABYSSALE_API_KEY"

Node.js

import abyssale from '@abyssale/sdk';

const { data, error } = await abyssale.listProjects();

if (error) console.error(error.id, error.message);
else console.log(data);

Python

from abyssale import Abyssale

with Abyssale() as client:
    result = client.list_projects()

print(result)

Example 200 response

[
  {
    "id": "d59adee9-4867-11f0-96f2-0a00d9eb8f78",
    "name": "HTML5 Tests",
    "created_at_ts": 1749827125,
    "category_name": "HTML5 Tests"
  }
]

Example 400 error response

{
  "id": "out_of_range",
  "message": "per_page must be at least 1",
  "errors": [
    {
      "path": "per_page",
      "code": "out_of_range",
      "message": "Must be at least 1, got 0."
    }
  ]
}

Retrieve the projects in your workspace, ordered by name. Projects group designs into logical collections. Only designs that belong to a project are accessible via the API.

Behaviour, limits and caveats

Filter by name and page with page / per_page — both optional: without them every project is returned, as a bare array. The number of matches is in the X-Total-Count header. Pass a project's id as project_id to GET /designs to list its designs.

Query parameters

name string

One exact phrase that must appear in the project name (case- and accent-insensitive).

page integer

1-based page number. Sending page or per_page turns paging on; without either, the listing returns every match, as it always has. Below 1 answers 400 out_of_range. Defaults to 1. Minimum 1.

per_page integer

Items per page when paging (see page). Values above 100 are treated as 100; below 1 answers 400 out_of_range. Defaults to 25. Range 1–100.

Response 200

The workspace's projects.

Errors

Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.

Status	When
400	page or per_page is below 1 (out_of_range) or not a number (wrong_type).
401	Unauthorized — missing or invalid API key.
429	Too Many Requests.
500	Internal Server Error — an unexpected error occurred on our side.

Related

• Projects guide