Getting started overview

Pixela provides a RESTful API for users to log and visualize personal metrics, often referred to as "pixels" on a graph. The service is free to use and focuses on simplicity for tracking habits and custom data points (Pixela documentation homepage). Getting started involves creating a user account, obtaining an API token, and then sending HTTP requests to create graphs and post pixel data.

The core interaction with Pixela is through HTTP requests, primarily using POST, PUT, and DELETE methods for creating, updating, and deleting user data, graphs, and pixels. All requests require the user's API token for authentication, which is passed in the X-USER-TOKEN HTTP header (Pixela API authentication details).

This guide will walk you through the initial setup, including account creation and making your first API call to log a pixel. While Pixela offers a Go SDK, this guide will focus on cURL examples for broader applicability, as cURL is a common tool for interacting with RESTful APIs (cURL manual page).

Quick Reference: Pixela Getting Started Steps

Step What to Do Where
1. Create User Register a new user account with a username and API token. POST /v1/users endpoint
2. Create Graph Define a graph with an ID, name, unit, type, and color. POST /v1/users/<username>/graphs endpoint
3. Post Pixel Log a pixel (data point) for a specific date and graph. POST /v1/users/<username>/graphs/<graphID> endpoint
4. View Graph Access the generated graph in a web browser. https://pixe.la/v1/users/<username>/graphs/<graphID>.html

Create an account and get keys

Pixela does not require a traditional email/password registration. Instead, you create a user account directly through its API by specifying a username and an API token. This token serves as your authentication key for all subsequent API requests. It is important to choose a strong, unique token and keep it secure, as anyone with your username and token can modify your Pixela data.

1. Choose a Username and API Token

Select a username that will be part of your graph URLs (e.g., https://pixe.la/v1/users/YOUR_USERNAME/graphs/). Your API token should be a string of at least 8 characters, ideally a mix of uppercase and lowercase letters, numbers, and symbols to ensure security (Pixela user creation documentation).

2. Create Your User Account

Use a POST request to the /v1/users endpoint to create your account. Replace <YOUR_USERNAME> and <YOUR_API_TOKEN> with your chosen values.

curl -X POST https://pixe.la/v1/users -H 'Content-Type: application/json' -d '{"token":"<YOUR_API_TOKEN>","username":"<YOUR_USERNAME>","agreeTermsOfService":"yes","notMinor":"yes"}'

Upon successful creation, the API will return a JSON response similar to {"message":"Success.","isSuccess":true}. If you receive an error, check your JSON format and ensure the username is not already taken.

3. Keep Your API Token Secure

The API token you used during user creation is your primary credential for all Pixela API interactions. Pixela does not provide a way to retrieve this token if you lose it; you would need to create a new user account (Pixela user deletion documentation). Store it securely and avoid hardcoding it directly into client-side code or public repositories.

Your first request

After creating your user account, the next step is to create a graph and then post a pixel to it. This demonstrates the core functionality of logging data.

1. Create a Graph

Before you can post pixels, you need a graph to put them on. A graph requires a unique ID, a name, a unit (e.g., "commits", "pages"), a type (e.g., "int" for integer, "float" for decimal), and a color.

Use a POST request to /v1/users/<YOUR_USERNAME>/graphs. Replace placeholders with your values:

  • <YOUR_USERNAME>: The username you created.
  • <YOUR_API_TOKEN>: Your API token.
  • <GRAPH_ID>: A unique identifier for your graph (e.g., my-daily-activity).
  • <GRAPH_NAME>: A descriptive name (e.g., Daily Activity).
  • <UNIT>: The unit of measurement (e.g., count).
  • <TYPE>: Data type (int or float).
  • <COLOR>: One of shibafu, momiji, sora, ichou, ajisai, or kuro (Pixela graph creation options).
curl -X POST https://pixe.la/v1/users/<YOUR_USERNAME>/graphs -H 'X-USER-TOKEN:<YOUR_API_TOKEN>' -H 'Content-Type: application/json' -d '{"id":"<GRAPH_ID>","name":"<GRAPH_NAME>","unit":"<UNIT>","type":"<TYPE>","color":"<COLOR>"}'

A successful response will be {"message":"Success.","isSuccess":true}.

2. Post Your First Pixel

Now that you have a graph, you can post a pixel to it. A pixel represents a single data point for a specific date and graph. You need to provide the date in YYYYMMDD format and the quantity.

Use a POST request to /v1/users/<YOUR_USERNAME>/graphs/<GRAPH_ID>. Replace placeholders:

  • <YOUR_USERNAME>: Your username.
  • <YOUR_API_TOKEN>: Your API token.
  • <GRAPH_ID>: The ID of the graph you just created.
  • <DATE_YYYYMMDD>: The date for the pixel (e.g., 20260529 for May 29, 2026).
  • <QUANTITY>: The value for the pixel (e.g., 5).
curl -X POST https://pixe.la/v1/users/<YOUR_USERNAME>/graphs/<GRAPH_ID> -H 'X-USER-TOKEN:<YOUR_API_TOKEN>' -H 'Content-Type: application/json' -d '{"date":"<DATE_YYYYMMDD>","quantity":"<QUANTITY>"}'

A successful response will be {"message":"Success.","isSuccess":true}.

3. View Your Graph

After posting a pixel, you can view your graph in a web browser. The URL follows this pattern:

https://pixe.la/v1/users/<YOUR_USERNAME>/graphs/<GRAPH_ID>.html

Replace <YOUR_USERNAME> and <GRAPH_ID> with your actual values. You should see a graph with a single pixel representing the data point you just posted.

Common next steps

Once you have successfully created a user, a graph, and posted your first pixel, you can explore more advanced Pixela features:

  • Update Pixels: Modify the quantity of an existing pixel using a PUT request (Pixela update pixel documentation). This is useful for correcting entries or adjusting daily totals.
  • Delete Pixels: Remove a pixel for a specific date using a DELETE request (Pixela delete pixel guide).
  • Get Pixels: Retrieve pixel data for a graph using a GET request (Pixela get pixel reference).
  • Manage Graphs: Create multiple graphs for different metrics, update graph properties (like color or unit), or delete graphs as needed (Pixela graph management API).
  • Webhooks: Set up webhooks to trigger actions when pixels are posted or updated. This can integrate Pixela with other services (Pixela webhook documentation). For general information on webhooks, see the Twilio webhook security guide (Twilio webhook security guide).
  • Subgraphs and Customizations: Explore options for creating subgraphs or customizing graph appearance beyond the basic colors.
  • Automate Logging: Integrate Pixela into scripts or applications to automate the logging of daily activities or sensor data. For example, a cron job could automatically post your daily commit count from a Git repository or your steps from a fitness tracker (if you have an API for it).

Troubleshooting the first call

When making your first Pixela API calls, you might encounter common issues. Here are some troubleshooting tips:

  • Incorrect API Token: Double-check that the X-USER-TOKEN header contains the exact API token you provided during user creation. Tokens are case-sensitive.
  • Invalid JSON Format: Ensure your JSON payload is correctly formatted. Missing commas, unclosed quotes, or incorrect curly braces can cause parsing errors. Use a JSON validator if unsure.
  • Missing Required Parameters: Each API endpoint has specific required parameters. For example, when creating a user, token, username, agreeTermsOfService, and notMinor are mandatory. When creating a graph, id, name, unit, type, and color are required (Pixela API reference for required parameters).
  • Username/Graph ID Already Exists: If you try to create a user with an existing username or a graph with an existing ID under your username, the API will return an error. Choose unique identifiers.
  • HTTP Method Mismatch: Ensure you are using the correct HTTP method (POST, GET, PUT, DELETE) for the intended operation. For instance, creating a user or graph requires POST.
  • Network Connectivity Issues: Verify your internet connection and that you can reach https://pixe.la.
  • Error Messages: Pay close attention to the error messages returned by the Pixela API. They often provide specific details about what went wrong (e.g., "message":"Please agree to the terms of service.").
  • cURL Syntax Errors: If using cURL, ensure correct quoting for JSON strings and proper use of flags like -X for the HTTP method and -H for headers.