Private API projects

Project endpoints live under the Private API base URL:

https://pagoti.com/api/v1

All requests require Private API authentication. See the authentication guide.

Resource shape

Project responses may include fields such as:

{
  "data": {
    "hash_id": "abc123de",
    "name": "My Project",
    "slug": "my-project",
    "description": "Project description",
    "published": true,
    "published_at": "2026-03-31T10:00:00.000000Z",
    "public": true,
    "public_at": "2026-03-31T10:00:00.000000Z",
    "updated_at": "2026-03-31T10:00:00.000000Z",
    "pages_count": 3,
    "media_count": 8,
    "pages_limit": 100,
    "media_limit": 1000,
    "can_create_page": true,
    "can_create_media": true,
    "url": "https://pagoti.com/my-project"
  }
}

List projects

GET /api/v1/projects

Returns the projects visible to the authenticated token or user.

For API tokens, the list is filtered to the token's allowed project abilities.

Example

curl https://pagoti.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

Create project

POST /api/v1/projects

Creates a new project for the authenticated account.

JSON body

{
  "name": "My Project",
  "description": "Project description"
}

Validation rules

Required fields:

• name: string, minimum 3 characters, maximum 40 characters
• description: minimum 3 characters, maximum 155 characters

Optional fields:

• public_at
• published_at
• image when sending multipart/form-data

Optional field rules:

• public_at: valid timestamp
• published_at: valid timestamp
• image: image file up to 1024 KB, minimum 640x480, maximum 3840x2160

Notes:

• the slug is generated from name
• project slugs must be unique

Success response

Returns 201 Created with the new project resource.

Get project

GET /api/v1/projects/{project}

Requires:

• matching project:{id} scope on the token
• access:read

Returns the project resource for the given project hash_id.

Update project

PUT /api/v1/projects/{project}

Requires:

• matching project:{id} scope on the token
• access:write

Common fields

{
  "name": "Updated Project Name",
  "description": "Updated description"
}

Validation rules

Updatable fields:

• name: minimum 3 characters, maximum 40 characters
• description: minimum 3 characters, maximum 155 characters
• default_page_id: nullable, must belong to the same project
• theme_id: nullable, must belong to the same user
• public_at: nullable valid timestamp
• published_at: nullable valid timestamp
• image: nullable image file up to 1024 KB, minimum 640x480, maximum 3840x2160

Additional behavior:

• the slug is regenerated when name changes
• the generated slug must remain unique
• default_page_id may be supplied as a page hash_id
• theme_id may be supplied as a theme hash_id
• sending null or none for default_page_id or theme_id clears the value

Returns 200 OK with the updated project resource.

Delete project

DELETE /api/v1/projects/{project}

Requires:

• matching project:{id} scope on the token
• access:write

Returns 204 No Content.

Common errors

• 401 Unauthorized when authentication is missing
• 403 Forbidden when the token cannot access the project or lacks the required ability
• 404 Not Found when the project hash_id does not exist
• 422 Unprocessable Content when validation fails
• 429 Too Many Requests when the plan rate limit is exceeded