Content API

API reference for content management endpoints including Payload CMS and Builder.io

Content API

This section covers all content-related API endpoints, including both Payload CMS and Builder.io integrations.

Payload CMS API

Base URL

https://your-domain.com/api/payload

Authentication

All Payload CMS endpoints require authentication. Include the access token in the Authorization header:

Authorization: Bearer <access_token>

Collections

List Collections

GET /api/payload/collections

Get a list of all available collections.

Response

{
  collections: {
    slug: string;
    label: string;
    fields: Array<{
      name: string;
      type: string;
      required: boolean;
    }>;
  }[];
}

Documents

List Documents

GET /api/payload/collections/:collection

Get documents from a collection.

Query Parameters

{
  page?: number;       // Default: 1
  limit?: number;      // Default: 10
  sort?: string;       // Example: '-createdAt'
  where?: object;      // MongoDB-style query
  depth?: number;      // Relationship depth
}

Response

{
  docs: Array<{
    id: string;
    [key: string]: any;
    createdAt: string;
    updatedAt: string;
  }>;
  totalDocs: number;
  page: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPrevPage: boolean;
}

Get Document

GET /api/payload/collections/:collection/:id

Get a single document by ID.

Response

{
  id: string;
  [key: string]: any;
  createdAt: string;
  updatedAt: string;
}

Create Document

POST /api/payload/collections/:collection

Create a new document.

Request Body

{
  [field: string]: any;
}

Response

{
  id: string;
  [key: string]: any;
  createdAt: string;
  updatedAt: string;
}

Update Document

PATCH /api/payload/collections/:collection/:id

Update an existing document.

Request Body

{
  [field: string]: any;
}

Delete Document

DELETE /api/payload/collections/:collection/:id

Delete a document.

Response

{
  id: string;
  deleted: true;
}

Builder.io API

Base URL

https://your-domain.com/api/builder

Authentication

Include your Builder.io API key in the headers:

Authorization: Bearer <builder_api_key>

Content

Get Page Content

GET /api/builder/content/:model

Get content for a specific model.

Query Parameters

{
  url?: string;        // Current URL path
  apiKey: string;      // Builder public API key
  userAttributes?: {   // Targeting attributes
    device?: string;
    location?: string;
    [key: string]: any;
  };
}

Response

{
  id: string;
  name: string;
  data: {
    blocks: Array<{
      id: string;
      component: {
        name: string;
        options: Record<string, any>;
      };
      meta: {
        [key: string]: any;
      };
    }>;
    state: Record<string, any>;
    [key: string]: any;
  };
  variations?: Array<{
    id: string;
    name: string;
    data: Record<string, any>;
  }>;
}

Create Content

POST /api/builder/content/:model

Create new content for a model.

Request Body

{
  name: string;
  data: {
    blocks: Array<{
      component: {
        name: string;
        options: Record<string, any>;
      };
    }>;
    [key: string]: any;
  };
  published?: boolean;
  variations?: Array<{
    name: string;
    data: Record<string, any>;
  }>;
}

Update Content

PATCH /api/builder/content/:model/:id

Update existing content.

Request Body

{
  name?: string;
  data?: Record<string, any>;
  published?: boolean;
}

Components

List Components

GET /api/builder/components

Get registered components.

Response

{
  components: Array<{
    name: string;
    inputs: Array<{
      name: string;
      type: string;
      required?: boolean;
      defaultValue?: any;
    }>;
    defaults?: Record<string, any>;
  }>;
}

Preview URLs

Generate Preview URL

POST /api/builder/preview-url

Generate a preview URL for content.

Request Body

{
  modelId: string;
  contentId: string;
}

Response

{
  url: string;
  expiresAt: string;
}

Error Handling

Both APIs use standard HTTP status codes:

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 500: Internal Server Error

Error Response Format:

{
  error: {
    message: string;
    code?: string;
    details?: Record<string, any>;
  };
}

Examples

Fetching Content

import { getContent } from '@/lib/content';

async function fetchPageContent(slug: string) {
  try {
    const content = await getContent({
      model: 'page',
      slug,
      userAttributes: {
        device: 'desktop',
        loggedIn: true,
      },
    });

    return content;
  } catch (error) {
    console.error('Content fetch error:', error);
    return null;
  }
}

Creating Content

import { createContent } from '@/lib/content';

async function createPage(data: any) {
  try {
    const page = await createContent({
      model: 'page',
      data: {
        name: 'New Page',
        data: {
          blocks: [
            {
              component: {
                name: 'Hero',
                options: {
                  title: 'Welcome',
                  subtitle: 'This is a new page',
                },
              },
            },
          ],
        },
        published: false,
      },
    });

    return page;
  } catch (error) {
    console.error('Content creation error:', error);
    throw error;
  }
}

Best Practices

  1. Performance

    • Use pagination for large collections
    • Cache responses when possible
    • Implement proper error handling

  2. Security

    • Validate input data
    • Implement proper access control
    • Use environment variables for API keys

  3. Content Management

    • Use proper content versioning
    • Implement content previews
    • Handle draft/published states

  4. API Usage

    • Follow rate limiting guidelines
    • Implement proper error handling
    • Use TypeScript for type safety

Related Resources