Generate and Use API Tokens

What the Pixelesq API Is For

Pixelesq's dashboard is the standard way to manage your site, but some use cases call for programmatic access:

Import data from another CMS into Pixelesq collections
Export content for backups, migrations, or third-party publishing
Sync external data sources (inventory, user databases, event feeds) into collections
Trigger actions from external services (publish a page when a CI job succeeds, update a collection when a webhook fires)
Build custom dashboards or tools that surface Pixelesq data in your team's preferred interface
Automate repetitive tasks that would be tedious to do in the dashboard

Pixelesq exposes a GraphQL API for these use cases. GraphQL is a flexible query language that lets you fetch exactly the data you need in a single request.

Generate an API Token

API tokens authenticate your requests. Without one, the API rejects your calls.

In your Pixelesq dashboard, go to your user profile settings (usually via clicking your avatar in the sidebar).
Find the API Tokens section.
Click Generate Token.
Give the token a descriptive name (e.g., "Data import script", "Zapier automation", "Content sync cron").
Click generate. Pixelesq creates the token and displays it once.
Copy the token immediately and store it securely. This is the only time you will see the full token. Pixelesq stores only a hash after this screen is closed, so you cannot retrieve it later.

[Screenshot: API token generation with token displayed]

Store the Token Securely

Treat your API token like a password. It grants write access to your project. Best practices:

Do not commit tokens to Git. Use environment variables or secret management tools.
Do not share tokens in Slack, email, or chat. If you need to share access, generate a separate token for the recipient and revoke it when done.
Use different tokens for different integrations. One token for Zapier, another for your import script, another for a custom dashboard. This lets you revoke one without affecting others.
Rotate tokens periodically. Every 6-12 months, revoke old tokens and generate fresh ones.

Authenticate API Requests

To authenticate a request, include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Your HTTP client (curl, Postman, Axios, Apollo Client, etc.) sends this header with every request. Pixelesq's API validates the token and processes the request.

Example: Query All Pages

Using curl:

curl -X POST https://api.pixelesq.com/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { pages(projectId: \"YOUR_PROJECT_ID\") { results { id name slug } } }"
  }'

The response is JSON with the pages you requested. Adjust the query to fetch more or fewer fields.

Example: Create a Collection Entry

Using a JavaScript fetch call:

const response = await fetch('https://api.pixelesq.com/graphql', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PIXELESQ_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `mutation CreateEntry($collectionId: String!, $payload: CreateEntryDto!) {
      createEntry(collectionId: $collectionId, payload: $payload) {
        success
        entry { id name slug }
      }
    }`,
    variables: {
      collectionId: 'your-collection-id',
      payload: {
        name: 'New Blog Post',
        slug: 'new-blog-post'
      }
    }
  })
});
const data = await response.json();

This creates a new entry in the specified collection. After creation, use additional mutations to set field values and publish.

Common API Use Cases

Bulk Content Import

Migrate content from another CMS by querying your old data, transforming it to match your Pixelesq collection schema, and calling the create entry mutation for each item.

Scheduled Content Publishing

Schedule posts via an external scheduler (cron job, GitHub Actions, serverless function) that calls the publish mutation at specific times. Useful if you want fine-grained control beyond Pixelesq's built-in scheduling.

Data Sync from External Sources

Pull data from external APIs (e.g., product catalog, event feed, inventory) and sync to Pixelesq collections on a schedule. Your content stays in sync with the source of truth without manual editing.

Export for Backup

Periodically query all your content (pages, collections, entries) and save to local files or cloud storage as a backup. Useful for disaster recovery or if you ever need to migrate off Pixelesq.

Custom Dashboards

Build a team dashboard showing content metrics, publishing activity, or form submissions in a format that suits your workflow better than Pixelesq's built-in views.

Revoke Tokens

When a token is no longer needed (integration deprecated, team member left, suspected compromise), revoke it immediately:

Go to the API Tokens section of your profile.
Find the token in the list.
Click revoke.
Confirm.

Once revoked, any request using that token fails with an authentication error. This is the kill switch for compromised credentials.

Token Permissions

API tokens inherit the permissions of the user who created them. If you are an Owner, your tokens have owner-level access. If you are an Editor, tokens have editor access. If you are a Viewer, tokens have read-only access.

This means token permissions match your role. For least-privilege access (e.g., a script that only needs read access), create a separate user with Viewer role and generate tokens under that user.

Rate Limits

Pixelesq's API has rate limits to prevent abuse. Details vary by plan. Free plans have lower limits. Paid plans get higher limits. Enterprise gets custom limits.

Rate limits are typically expressed as requests per minute or per day. Exceeding limits returns a 429 error. Your client should handle this by backing off and retrying later.

Pro Tips

Use descriptive token names. "Token 1" means nothing. "Content sync cron (prod)" tells you exactly what the token does and helps you decide whether to revoke it.
Store tokens in environment variables. Never hardcode tokens in source code or commit them to Git. Use .env files (gitignored) or your deployment platform's secret management.
Test API calls in a non-production environment first. Mutations can create, modify, or delete content. Test in a sandbox project before running against production data.
Use GraphQL's selection syntax efficiently. Query only the fields you need. Over-fetching wastes bandwidth and slows responses.
Keep track of which tokens exist. Maintain a list outside of Pixelesq (e.g., a private spreadsheet) mapping token names to their purposes and the scripts that use them. Makes rotation and revocation easier.

Troubleshooting

API returns 401 Unauthorized: Your token is invalid, expired, or missing. Confirm the Authorization header is formatted correctly: Bearer YOUR_TOKEN. Check that the token has not been revoked in Pixelesq.

API returns 403 Forbidden: The token is valid but lacks permission for the requested action. Check the role of the user who owns the token. Viewer tokens cannot write; Editor tokens cannot manage team.

API returns 429 Too Many Requests: Rate limit exceeded. Back off and retry after a delay. Consider caching responses or batching requests to reduce API calls.

GraphQL query returns errors: The error response includes specific details. Common issues: wrong field names, missing required arguments, invalid IDs. Read the error message and fix the query.

Token generation is not available: API tokens may be restricted to certain user roles or plans. Check your plan details or contact support if you believe you should have access but do not see the option.

FAQ

Is there an SDK or client library for the Pixelesq API?

Pixelesq's API is GraphQL, so any GraphQL client works: Apollo Client, URQL, graphql-request (for Node.js), gql (for Python), or even plain fetch/curl. There may or may not be an official Pixelesq SDK depending on the current development state; check the developer documentation.

Can I use the API without generating a token?

No. All API requests require authentication via a token. Unauthenticated requests are rejected. This is a security measure to prevent unauthorized access to your project data.

What is the difference between an API token and an OAuth token?

API tokens are long-lived credentials you generate and manage yourself. OAuth tokens are obtained through an authorization flow with a third-party service and have limited lifetimes. Pixelesq uses API tokens for most programmatic access. Some integrations (like Slack, Linear, GSC) use OAuth internally but the user-facing model is token-based.

Are there webhooks available as an alternative to polling the API?

Yes. Pixelesq webhooks push events to your URL in real time, which is more efficient than polling the API. Use webhooks for event-driven integrations (reacting to form submissions, publishes, entry changes). Use the API for proactive operations (creating content, running queries, exporting data). See our guide on setting up webhooks.

Can I rate-limit my API calls myself to stay within limits?

Yes, and you should. Most GraphQL clients support rate limiting, retry with backoff, or request queuing. Implement these at your client level to avoid hitting Pixelesq's limits. Treat limits as hard caps, not targets.

If I expose my API token in a frontend bundle, what is the risk?

High. Frontend code runs in users' browsers, so anyone can inspect it and extract your token. An exposed token can be used to read and modify your project. Never put API tokens in frontend code. All API calls should go through your backend, which holds the token securely. If you need frontend-facing data, expose it through your backend with appropriate auth checks.

How to Generate and Use API Tokens