List projects

Returns all projects, with optional filtering by phase and node.

GET /api/v1/projects

Query parameters

string

Filter by lifecycle phase. Accepted values: Pending, Scheduled, Running, Failed, Terminating, Terminated.You can repeat this parameter to match multiple phases (OR logic):?phase=Scheduled&phase=RunningWhen combined with nodeRef, both filters are applied (AND logic).

string

Filter by the name of the node the scheduler assigned to the project. Projects in Pending phase have no nodeRef and are excluded when this filter is set.

Response

Returns a ProjectList object.

string

required

Always "caravanserai/v1".

string

required

Always "ProjectList".

object[]

required

Array of Project objects. Empty when no projects match.

Show items[]

string

Always "caravanserai/v1".

string

Always "Project".

object

Show properties

string

required

Unique name of the project.

object

Arbitrary key/value string pairs.

object

Non-identifying key/value metadata.

string

RFC 3339 timestamp set by the server on first write.

string

RFC 3339 timestamp updated by the server on every write.

object

Show properties

object[]

required

Ordered list of container definitions.

object[]

Named storage volumes shared across services.

object[]

HTTP ingress routing rules.

string

RFC 3339 timestamp after which the GC controller deletes the project.

object

Show properties

string

Current lifecycle phase: Pending, Scheduled, Running, Failed, Terminating, or Terminated.

string

Name of the node assigned by the scheduler. Empty while Pending.

object[]

Granular observable states. See Get project for the full condition schema.

Examples

curl http://localhost:8080/api/v1/projects

curl "http://localhost:8080/api/v1/projects?phase=Running"

curl "http://localhost:8080/api/v1/projects?nodeRef=worker-01"

curl "http://localhost:8080/api/v1/projects?phase=Scheduled&phase=Running"

{
  "apiVersion": "caravanserai/v1",
  "kind": "ProjectList",
  "items": [
    {
      "apiVersion": "caravanserai/v1",
      "kind": "Project",
      "metadata": {
        "name": "nginx-demo",
        "createdAt": "2025-04-06T10:00:00Z",
        "updatedAt": "2025-04-06T10:00:05Z"
      },
      "spec": {
        "services": [
          {
            "name": "web",
            "image": "nginx:alpine"
          }
        ]
      },
      "status": {
        "phase": "Running",
        "nodeRef": "worker-01",
        "conditions": [
          {
            "type": "Phase",
            "status": "True",
            "reason": "AgentReady",
            "message": "All containers are running",
            "lastTransitionTime": "2025-04-06T10:00:05Z"
          }
        ]
      }
    }
  ]
}

Overview

Nodes

Projects

Query parameters

Response

Examples

​Query parameters

​Response

​Examples

Query parameters

Response

Examples