GET /v1/post-types

List the post types configured on the site that owns the API key, along with their field schemas. Use this endpoint to discover what post_type slugs are valid before calling POST /v1/posts.

• URL: https://api.canverly.com/v1/post-types
• Method: GET
• Auth: Bearer API key
• Required scope: post_types:read
• Rate limit: 60 req/min per key

Request

Query parameters

Param	Type	Default	Description
include_archived	boolean	false	Include post types that were soft-deleted.
q	string	—	Case-insensitive substring filter on slug or label.
limit	integer	50	Page size, max 200.
cursor	string	—	Opaque pagination cursor from previous response’s next_cursor.

Example

curl https://api.canverly.com/v1/post-types?q=event \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

200 OK

{
  "data": [
    {
      "id": "01HZX9KPTPOST_TYPE0000000001",
      "slug": "post",
      "label": "Post",
      "description": "Default blog post type.",
      "is_builtin": true,
      "fields": [
        { "name": "title", "type": "string", "required": true, "max_length": 240 },
        { "name": "slug", "type": "slug", "required": false },
        { "name": "excerpt", "type": "string", "required": false, "max_length": 500 },
        { "name": "content_html", "type": "html", "required": true },
        { "name": "cover_image_url", "type": "url", "required": false },
        { "name": "tags", "type": "string[]", "required": false },
        { "name": "published_at", "type": "datetime", "required": false }
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "01HZX9KPTPOST_TYPE0000000002",
      "slug": "event",
      "label": "Event",
      "description": "Calendar entries with start/end times.",
      "is_builtin": false,
      "fields": [
        { "name": "title", "type": "string", "required": true },
        { "name": "content_html", "type": "html", "required": true },
        { "name": "starts_at", "type": "datetime", "required": true },
        { "name": "ends_at", "type": "datetime", "required": true },
        { "name": "venue", "type": "string", "required": false }
      ],
      "created_at": "2026-03-14T10:00:00Z",
      "updated_at": "2026-04-02T09:30:00Z"
    }
  ],
  "next_cursor": null
}

Field schema types

type	Meaning
string	Plain UTF-8 text. May carry max_length.
slug	URL-safe lowercase, hyphenated.
html	Sanitized HTML (Canverly strips <script>, event handlers).
url	Absolute URL. cover_image_url requires HTTPS.
datetime	ISO 8601 UTC.
string[]	Array of strings.
int / float	Numeric. May carry min / max.
bool	Boolean.
enum	Carries options[].
relation	Reference to another post (target_post_type slug).

Use fields[] to validate the body of POST /v1/posts client-side — anything not listed as required: true may be omitted.

Pagination

Responses are cursor-paginated. When next_cursor is non-null, fetch the next page by passing ?cursor=<value>. When it is null, you have the last page.

Errors

Status	type slug	When
401	unauthenticated	Missing/invalid Authorization.
403	insufficient-scope	Key lacks post_types:read.
429	rate-limited	Exceeded 60 req/min.