Private API pages

Page endpoints are nested under a project:

https://pagoti.com/api/v1/projects/{project}/pages

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

Resource shape

Page responses may include fields such as:

{
  "data": {
    "hash_id": "abcd1234",
    "name": "Getting started",
    "slug": "getting-started",
    "description": "A short summary",
    "markdown": "# Getting started",
    "html": "<h1>Getting started</h1>",
    "published": true,
    "published_at": "2026-03-31T10:00:00.000000Z",
    "updated_at": "2026-03-31T10:00:00.000000Z",
    "word_count": 120,
    "project_hash_id": "abc123de"
  }
}

List pages

GET /api/v1/projects/{project}/pages

Requires:

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

Returns paginated pages for the specified project, including unpublished pages when the token is authorized.

Get page

GET /api/v1/projects/{project}/pages/{page}

Requires:

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

Returns a single page resource, including rendered html.

Create page

POST /api/v1/projects/{project}/pages

Requires:

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

JSON body

{
  "name": "New page",
  "description": "A short summary"
}

Validation rules

Required fields:

• name: minimum 3 characters, maximum 64 characters
• description: minimum 3 characters, maximum 155 characters

Optional fields:

• published_at
• image when sending multipart/form-data

Optional field rules:

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

Notes:

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

Returns 201 Created with the new page resource.

Update page

PUT /api/v1/projects/{project}/pages/{page}

Requires:

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

Content update

To replace the markdown content directly:

{
  "markdown": "# Updated content"
}

Metadata update

To update page metadata:

{
  "name": "Updated page name",
  "description": "Updated description",
  "published_at": "2026-03-31T10:00:00.000000Z"
}

Content and metadata fields can be updated in the same request:

{
  "name": "Updated page name",
  "markdown": "# Updated content"
}

Validation rules

When updating metadata:

• name: required when present, minimum 3 characters, maximum 64 characters
• description: required when present, minimum 3 characters, maximum 155 characters
• published_at: nullable valid timestamp
• image: nullable image file up to 1024 KB, minimum 640x480, maximum 3840x2160

When updating content:

• markdown: required when present, maximum 65535 characters

Additional behavior:

• only fields included in the request are updated
• content and metadata fields may be updated together
• when name changes, the slug is regenerated
• regenerated slugs must remain unique within the project

Returns 200 OK with the refreshed page resource.

Delete page

DELETE /api/v1/projects/{project}/pages/{page}

Requires:

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

Returns 204 No Content.

Route scoping

Pages are scoped to their parent project. If the page does not belong to the {project} in the URL, the API returns 404 Not Found.

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 or page hash_id does not exist, or the page does not belong to the project
• 422 Unprocessable Content when validation fails
• 429 Too Many Requests when the plan rate limit is exceeded