Skip to content
hydrate.sh droplet markhydrate.sh

List your projects

GET
/v1/projects
curl --request GET \
  --url 'https://api.hydrate.sh/v1/projects?limit=100&include_archived=false' \
  --header 'Authorization: Bearer <token>'

Returns the projects the caller can see. For API-key callers the list is further filtered by the per-key project allowlist (if configured). Archived projects are excluded. An empty list is a normal response when the caller has no visible projects. Archived projects are excluded unless include_archived=true.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
Limit

Maximum projects to return. Defaults to 100; max 200.

integer
default: 100 >= 1 <= 200

Maximum projects to return. Defaults to 100; max 200.

include_archived
Include Archived

Include archived projects. Off by default. Needed by name-addressed callers such as the CLI: an archived project that cannot be listed cannot be renamed or restored, which would make archiving a one-way door.

boolean

Include archived projects. Off by default. Needed by name-addressed callers such as the CLI: an archived project that cannot be listed cannot be renamed or restored, which would make archiving a one-way door.

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
ProjectsListResponse
object
projects
required
Projects
Array<object>
ProjectOut
object
archived
required
Archived
boolean
created_at
required
Created At
string
h2o_schema_version
required
H2O Schema Version
integer
id
required
Id
string format: uuid
intent
required
Any of:
string
language
required
Any of:
string
last_opened_at
required
Any of:
string
name
required
Name
string
updated_at
required
Updated At
string
version
required
Version
string
Examplegenerated
{
  "projects": [
    {
      "archived": true,
      "created_at": "example",
      "h2o_schema_version": 1,
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "intent": "example",
      "language": "example",
      "last_opened_at": "example",
      "name": "example",
      "updated_at": "example"
    }
  ],
  "version": "example"
}

401

Section titled “401”

No credentials, malformed credentials, or revoked credentials. The envelope is leak-parity (same shape across all 401 paths) so an attacker cannot distinguish revoked vs. unknown via the body.

Media typeapplication/json
object
detail
required
string
Example
{
  "detail": "unauthenticated"
}

403

Section titled “403”

Credentials are valid but lack the scope required for this route, or the principal lacks membership in the target project.

Media typeapplication/json
object
detail
object
code
string
message
string
Examplegenerated
{
  "detail": {
    "code": "example",
    "message": "example"
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

429

Section titled “429”

Per-bucket rate limit exceeded. The response carries Retry-After and the standard X-RateLimit-* headers (Limit / Remaining / Reset).

Media typeapplication/json
object
detail
string
Example
{
  "detail": "rate_limited"
}

Headers

Section titled “Headers”
Retry-After
integer
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
X-RateLimit-Reset
integer