Codeshots

API Documentation

Authentication

All API requests require authentication via an API key. Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY
Getting an API Key

Sign in to your dashboard to create and manage your API keys. Keep your API keys secret.

POST/api/v1/images

Generate syntax-highlighted code images by sending a JSON request body with your code, language, and styling preferences. The API returns the image directly as binary data.

Parameters

Parameter
code
Type
string
Required
Yes
Default
—
Description
The source code to highlight (1–10,000 characters).
Parameter
language
Type
string
Required
No
Default
"plaintext"
Description
Programming language for syntax highlighting. One of: typescript, javascript, python, rust, go, java, html, css, json, bash, sql, yaml, markdown, plaintext.
Parameter
format
Type
string
Required
No
Default
"png"
Description
Image format. One of: png, webp, jpeg.
Parameter
scale
Type
string
Required
No
Default
2
Description
Resolution multiplier. One of: 1, 2, 3.
Parameter
style
Type
object
Required
No
Default
—
Description
Visual styling options for the generated image.

Style object

Property
theme
Type
string
Default
"github-dark"
Description
Color theme. One of: github-dark, github-light, dracula, nord, one-dark-pro, monokai, vitesse-dark, vitesse-light, solarized-dark, solarized-light.
Property
showWindowControls
Type
boolean
Default
true
Description
Whether to display window control buttons.
Property
showLineNumbers
Type
boolean
Default
true
Description
Whether to show line numbers.
Property
fontSize
Type
number
Default
14
Description
Font size in pixels (10–32).
Property
lineHeight
Type
number
Default
1.5
Description
Line height multiplier (1–2.5).
Property
fontFamily
Type
string
Default
"JetBrains Mono"
Description
Monospace font. One of: JetBrains Mono, Fira Code, Source Code Pro.
Property
background
Type
string
Default
"twilight"
Description
Background preset. One of: twilight, ocean, sunset, candy, midnight, breeze, arctic, noir, slate, white, indigo.
Property
aspectRatio
Type
string
Default
"auto"
Description
Constrains the output image to a fixed aspect ratio. One of: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 7:8. When not auto, the background expands to fill the target ratio.

Response format

Success (200)

Returns the image as binary data with the appropriate Content-Type header (image/png, image/webp, or image/jpeg).

Error (401)

Missing or invalid API key.

{
  "error": "Missing API key. Provide it via Authorization: Bearer <key>"
}

Error (400)

{
  "error": "Invalid request body",
  "details": "..."
}

Error (500)

{
  "error": "Failed to generate image"
}

Example

curl -X POST 'https://codeshots.dev/api/v1/images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "console.log(\"Hello, world!\")",
  "language": "javascript",
  "format": "png",
  "scale": 2,
  "style": {
    "theme": "github-dark",
    "showWindowControls": true,
    "showLineNumbers": true,
    "fontSize": 14,
    "lineHeight": 1.5,
    "fontFamily": "JetBrains Mono",
    "background": "twilight",
    "aspectRatio": "16:9"
  }
}' \
  --output image.png

Interactive playground

Try the API directly from your browser. Adjust the parameters, see the generated cURL command, and send the request.

Get your API key from the dashboard

Code
Output
Style
14

cURL command

curl -X POST '/api/v1/images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "function greet(name: string): string {\n  return `Hello, ${name}!`;\n}",
  "language": "typescript",
  "format": "png",
  "scale": 2,
  "style": {
    "theme": "github-dark",
    "showWindowControls": true,
    "showLineNumbers": true,
    "fontSize": 14,
    "fontFamily": "JetBrains Mono",
    "background": "twilight",
    "aspectRatio": "auto"
  }
}' \
  --output image.png
GET/api/v1/cache

Retrieve cache statistics for your account. Returns the number of cached images and how long each entry is retained.

Response format

Success (200)

{
  "entryCount": 42,
  "ttlInSeconds": 604800
}

entryCount is the number of images currently cached for your account. ttlInSeconds is the time-to-live each cache entry is stored for before expiring.

Error (401)

Missing or invalid API key.

{
  "error": "Missing API key. Provide it via Authorization: Bearer <key>"
}

Example

curl 'https://codeshots.dev/api/v1/cache' \
  -H 'Authorization: Bearer YOUR_API_KEY'
DELETE/api/v1/cache

Clear all cached images for your account, regardless of which API key was used to generate them. Returns the number of entries that were removed.

Response format

Success (200)

{
  "clearedCount": 42
}

clearedCount is the number of cache entries that were removed. Returns 0 if there was nothing to clear.

Error (401)

Missing or invalid API key.

{
  "error": "Missing API key. Provide it via Authorization: Bearer <key>"
}

Example

curl -X DELETE 'https://codeshots.dev/api/v1/cache' \
  -H 'Authorization: Bearer YOUR_API_KEY'