canonical: https://jentic.com/apis/codestats.net/codestats

# Code::Stats API

Jentic publishes the only available OpenAPI specification for Code::Stats API, keeping it validated and agent-ready. Code::Stats is a free, open-source programming activity tracker - editor plugins watch what a developer types in each language and report XP (experience points) to a hosted profile that visualises long-term coding activity. The API has just 2 endpoints over codestats.net/api: GET `/users/{username}` returns a public profile with per-language XP and totals, and POST `/my/pulses` lets a client submit a fresh pulse of XP gained against one or more languages. Pulse submission requires a signed API token (X-API-Token header).

## For AI agents

Read a Code::Stats user profile or submit a programming-activity pulse with per-language XP using an X-API-Token header.

## Scope

Does not handle private profile data, account creation, or aggregated leaderboards - use for public profile reads and personal pulse submission only.

## Capabilities

- Submit a pulse of XP across one or more programming languages via POST `/my/pulses`
- Read any user's public profile, including total XP and per-language breakdowns, via GET `/users/{username}`
- Calculate level progress from XP using the published formula (level = floor(0.025 * sqrt(xp)))
- Compare two developers' per-language XP for friendly competition or onboarding metrics
- Drive a custom editor plugin or CI hook that reports coding activity to Code::Stats

## Use cases

### Custom Editor Activity Reporting

Developers using editors that lack an official Code::Stats plugin can build a thin client that posts pulses through POST `/my/pulses.` Each save or focus event accumulates XP per language and is flushed periodically. Lets unsupported tools (custom IDEs, terminal-based editors, niche notebooks) participate in the same long-term activity profile as the official plugins.

Example prompt: Buffer typed-character counts per language for 60 seconds, then POST `/my/pulses` with coded_at=now and an xps array of {language, xp} pairs

### Developer Profile Embed for a Personal Site

Embed live Code::Stats data in a personal website by calling GET `/users/{username}` server-side and rendering total XP, top languages, and recent activity. The page stays in sync with the developer's coding activity without manual updates. Replaces stale 'I work in Rust and Python' bullet points with data sourced from the editor itself.

Example prompt: Call GET `/users/alice`, extract the top 5 languages by XP, and render them as a sorted list on the personal site

### Team or Cohort Activity Dashboard

Bootcamps and engineering teams use Code::Stats to give learners and members a shared, public view of their progress. The agent loops over a list of usernames calling GET `/users/{username}` and aggregates XP into a leaderboard or cohort dashboard. Builds friendly motivation around consistent practice rather than headline output.

Example prompt: For each username in cohort.csv call GET `/users/{username}`, sum total XP for the last 30 days, and render a leaderboard

### Agent-Driven Code::Stats via Jentic

An AI agent connected to Jentic can answer 'how much XP did I earn this week?' or post a pulse from a custom toolchain without holding the raw signed token. Jentic stores the X-API-Token in its vault and executes `/users/{username}` or `/my/pulses` on the agent's behalf, returning parsed responses.

Example prompt: Search Jentic for 'submit Code::Stats pulse', load the POST `/my/pulses` schema, and execute it with coded_at=now and xps=[{language: 'Python', xp: 100}]

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/users/{username}` | Get a user's public profile |
| POST | `/my/pulses` | Submit a programming-activity pulse |

## Key resources

- **User profile** — Read public profile data including total XP, per-language XP, and recent activity
- **Pulses** — Submit XP earned against one or more programming languages from a custom client

## Why Jentic

- **Setup:** Wiring Code::Stats by hand means sending its signed X-API-Token header, targeting codestats.net/api, and separating public profile reads from personal pulse submission yourself. Through Jentic you install once, import the Code::Stats API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Code::Stats reads a public profile by username in the URL path (`/users/{username}`) and submits a pulse through the request body (`/my/pulses`), so scope the agent by operations: limit it to the operations it needs, such as reading a profile or submitting a pulse. The operations you allow are the only ones that run.
- **Credential handling:** Your signed Code::Stats X-API-Token is stored once, encrypted, by your own Jentic One instance and injected at execution time as the X-API-Token header. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit a Code::Stats pulse' or 'read a user's coding profile', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GitHub API** — Pair with Code::Stats to combine commit-level activity (GitHub) with editor-level XP (Code::Stats)
- **Stack Exchange API** — Pull a developer's reputation and answers from Stack Overflow alongside Code::Stats activity
- **GitLab API** — Add GitLab commit and merge request activity for users hosting code on GitLab

## FAQ

### Why is there no official OpenAPI spec for Code::Stats API?

Code::Stats does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Code::Stats API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Code::Stats API use?

Profile reads at GET `/users/{username}` are public and need no auth. Pulse submission at POST `/my/pulses` requires a signed token in the X-API-Token header, generated in the Code::Stats Machine control panel. Through Jentic the token is stored in the vault.

### Can I submit programming activity from a custom editor?

Yes. POST `/my/pulses` accepts a coded_at timestamp and an xps array of {language, xp} entries, so any tool that observes coding activity can report it. Bundle multiple languages in one pulse if a session crosses files of different types.

### What are the rate limits for the Code::Stats API?

Code::Stats does not publish a fixed public rate limit. The service is community-run, so pulse submission frequency should match the official plugins (one pulse every minute or so) and profile reads should be cached. Back off on HTTP 429 responses.

### How do I read a user profile through Jentic?

Search Jentic for 'get Code::Stats user profile', load the GET `/users/{username}` schema, and execute it with the username. The endpoint is unauthenticated, so Jentic simply returns the parsed profile including total XP and per-language XP.

### Can I limit what my agent is allowed to do with the Code::Stats API?

Yes. Because Jentic One is self-hosted, your own rules decide which Code::Stats operations the agent may call, and the operations you allow are the only ones that run. This API has just two operations: reading a public profile with GET `/users/{username}` and submitting a pulse with POST `/my/pulses`, so you can restrict a read-only agent to profile lookups while withholding pulse submission, or the reverse. Your signed X-API-Token is held by your own instance and injected only when an allowed operation runs, never in the agent's prompt or logs.