Molodetz documentation

Auto-generated from the live docs registry. Give this file to an agent to learn the API.

Molodetz is an independent institute for the study and practice of software engineering. This documentation describes how the site works, how to use the API and how admin keeps the whole thing running.

Read Writing on the roll for the content, and API and authentication for integrations.

Posts are markdown and live in SQLite. Only administrators write. A post has a title, a topic (roll or standard), a status (draft or published) and an optional placeholder marker.

The server renders GFM: tables, strikethrough, hard line breaks. HTML in the text is escaped. Links may only be http, https, mailto and tel. Write emoji as :shortcode:, for example :fire:.

A bare image URL becomes an image, @name becomes a link to the profile.

The first notes were carried over from the earlier Molodetz page and carry the Placeholder label. The institute replaces them with finished essays. Untick the box while editing once a note is complete.

A slug is the title plus the last twelve characters of the uid. Editing does not change the slug. If a title is ever rewritten in the database, the old slug still resolves through its uid tail and redirects with 301 to the canonical one.

The form at /join stores a join request: name, contact, an optional link to your work and a message. Administrators get a notification and see the request under Admin, Join requests.

There is no automatic access. retoor reads every request himself and answers the strong ones.

Molodetz has no ads, no cross-app tracking, no payments and no social login.

Every route has four faces: HTML, JSON, documentation and (where selected) an assistant tool. Ask for JSON with Accept: application/json.

Resolution order:

  1. session cookie (64 hex characters) after logging in at /auth/login.
  2. X-API-KEY header with your API key.
  3. Authorization: Bearer <key>.
  4. Authorization: Basic with name or email and password.

There is no JWT and no OAuth.

curl -H 'Accept: application/json' https://molodetz.nl/roll

Errors have the shape {"error": {"status": 404, "message": "..."}}. Validation errors return 422 with {"error": "validation", "fields": [...], "messages": [...]}.

Membership starts from a join request plus an admin-issued invite. Admins call POST /admin/joins/{uid}/invite (returns claim_url and expires_at in data) and POST /admin/joins/{uid}/invite/revoke. The public claim is GET and POST /invite/{token} with username, email, password, password_confirm and terms. Claim links are single use and every dead link answers 404 with the same message.

GET /admin/gallery reports live flyer and meme counts plus catalogued source files missing from disk. POST /admin/gallery/resync re-reads the sources and retires removed entries. See Galleries and content for how publishing works.

The Dutch paths from before (/rol, /standaard, /mensen, /binnen, /voorwaarden) answer with a 301 to their English replacement. Query strings are kept.

The flyers and the memes are curated galleries. Every work is a source file plus a catalogue entry with its caption. Nothing is uploaded through the site: new works arrive with a deploy, and the database reconciles at boot.

Flyers live at /flyers. New flyers are 1080 by 1350 (portrait). The first flyer in the catalogue is the featured one on the home page.

Memes live at /memes. New memes are 1080 by 1080 (square). Some older memes are 1280 by 720 (landscape) from the previous generation; they stay as they are.

  1. The source file lands in the media directory and the catalogue entry (filename, kind, caption) lands in the code, both through deploy.
  2. At boot the sync reads every catalogued source file and upserts the database row: position, dimensions, perceptual hash and a generated webp thumbnail.
  3. Near-duplicates are skipped: a work whose image hash is within a small distance of an already synced work is logged and left out, so an accidental double never shows twice.
  4. Removed works are retired, never hard-deleted: their rows are soft-deleted and disappear from the galleries.

An administrator can also press Resync under Admin, Gallery after a deploy. Resync re-reads the sources, refreshes thumbnails whose content changed, reports missing source files and retires removed entries. It never invents catalogue entries.

Public pages are cached for seconds to minutes (landing, settings, sitemap each have their own short TTL), so a fresh deploy can take a moment to show everywhere. The exact TTLs are operator detail; see the operator runbook under Admin.

Old Dutch paths (/rol, /mensen, and friends) redirect with 301 to their English replacements; see API and authentication.

Skills are small agent packages published on this site. Each skill is one
directory with a SKILL.md file plus optional scripts, references, and
assets, following the open Agent Skills standard from agentskills.io.

Every skill carries a short and a long description, both from the same
specification so every skill reads the same way.

Short: the frontmatter description in SKILL.md. One to 1024 characters
stating what the skill does and when to use it, with trigger keywords.
Agents load every installed short description at startup, and the skills
list shows exactly this text per skill.

Long: the markdown body after the frontmatter. Rendered on the skill page
below the facts table. It starts with one H1 title, then the fixed
sections What it does, When to use, Instructions, Examples, References.
Keep it concise and under 500 lines; move detail into references/ files
and deterministic work into scripts/.

The name is 1 to 64 characters of lowercase letters, digits, and
hyphens, with no leading, trailing, or consecutive hyphens, and it must
match the skill directory name. Optional fields are license,
compatibility (1 to 500 characters, only when the skill needs a
specific environment), metadata (a string map, used here for author and
version), and the experimental allowed-tools.

Admins author skills at /admin/skills: New skill writes a fresh
SKILL.md, Edit rewrites an existing one. Every save validates in the
official way: strict specification checks first, then
muse skills validate on the written directory. A save lands only when
both pass; a failed create removes its directory and a failed update
restores the previous file. Draft from prompt asks the configured model
to propose both descriptions, which the admin reviews before saving.

The skill page lists the full file tree with per-file downloads and one
ZIP holding the whole package. Build artifacts and hidden files are
excluded from both. The skills index and every skill page are indexed
and listed in the sitemap.

API reference

API: Content

Public read routes: the roll, the standard, posts, galleries and people.

GET /

Home · auth public (guest) · negotiable

Latest posts and the featured flyer.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/'

Response sample

{
  "flyer_count": 4,
  "meme_count": 22,
  "posts": []
}

GET /roll

The roll · auth public (guest) · negotiable

Published notes in the roll topic, newest first, cursor paginated.

Fields

NameTypeLocationRequiredExample
beforestringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/roll'

Response sample

{
  "next_cursor": null,
  "posts": [],
  "title": "Roll",
  "topic": "roll"
}

GET /standard

The standard · auth public (guest) · negotiable

Published posts in the standard topic.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/standard'

Response sample

{
  "posts": [],
  "title": "Standard",
  "topic": "standard"
}

GET /posts/{slug}

Post · auth public (guest) · negotiable

A published post by slug or uid. Old slugs redirect with 301 to the canonical slug.

Fields

NameTypeLocationRequiredExample
slugstringpathyeson-finishing

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/posts/on-finishing'

Request JSON

{
  "path": {
    "slug": "on-finishing"
  }
}

Response sample

{
  "author": {
    "username": "retoor"
  },
  "post": {
    "title": "On finishing.",
    "topic": "roll"
  }
}

GET /flyers

Flyers · auth public (guest) · negotiable

Flyer gallery.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/flyers'

Response sample

{
  "items": [],
  "kind": "flyer",
  "title": "Flyers"
}

GET /memes

Memes · auth public (guest) · negotiable

Meme gallery.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/memes'

Response sample

{
  "items": [],
  "kind": "meme",
  "title": "Memes"
}

GET /people

People · auth public (guest) · negotiable

People on the roll.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/people'

Response sample

{
  "people": [
    {
      "post_count": 5,
      "username": "retoor"
    }
  ]
}

GET /people/{username}

Person · auth public (guest) · negotiable

Profile with posts.

Fields

NameTypeLocationRequiredExample
usernamestringpathyesretoor

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/people/retoor'

Request JSON

{
  "path": {
    "username": "retoor"
  }
}

Response sample

{
  "person": {
    "username": "retoor"
  },
  "posts": []
}

GET /robots.txt

robots.txt · auth public (guest) · none

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/robots.txt'

Response sample

null

GET /sitemap.xml

Sitemap · auth public (guest) · none

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/sitemap.xml'

Response sample

null

GET /avatar/svg/{seed}

Avatar · auth public (guest) · none

Deterministic SVG avatar.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/avatar/svg/{seed}'

Response sample

null

GET /health

Health · auth public (guest) · json

Liveness and version.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/health'

Response sample

{
  "status": "ok",
  "version": "1.0.0"
}

GET /presence/roster

Presence · auth public (guest) · json

Online set (uids).

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/presence/roster'

Response sample

{
  "online": [],
  "tracked": 0
}

API: Join

Apply to contribute. Stored for administrators, never public.

GET /join

Join form · auth public (guest) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/join'

Response sample

{
  "submitted": false
}

POST /join

Apply to join · auth public (guest) · negotiable

Stores a join request: name, contact and an optional repo link.

Fields

NameTypeLocationRequiredExample
namestringbodyyesAda
contactstringbodyyesada@example.com
repo_urlstringbodynohttps://git.example.com/ada
messagestringbodynoI write about finishing things.

Request sample

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"name": "Probe", "contact": "probe@example.com"}' 'https://example.com/join'

Request JSON

{
  "contact": "probe@example.com",
  "name": "Probe"
}

Response sample

{
  "data": {
    "uid": "0190..."
  },
  "ok": true,
  "redirect": "/join?ok=1"
}

GET /invite/{token}

Invite claim form · auth public (guest) · negotiable

Shows the claim form for a live invite; unknown, used and expired links answer 404 with the same message.

Fields

NameTypeLocationRequiredExample
tokenstringpathyesunknown-token

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/invite/unknown-token'

Request JSON

{
  "path": {
    "token": "unknown-token"
  }
}

Response sample

{
  "email": "ada@example.com",
  "email_locked": true,
  "username": "ada",
  "valid": true
}

POST /invite/{token}

Claim invite · auth public (guest) · negotiable

Creates the Member account, logs in and marks the join request accepted. Single use.

Fields

NameTypeLocationRequiredExample
tokenstringpathyesunknown-token
usernamestringbodyyesada
emailstringbodyyesada@example.com
passwordstringbodyyescorrect horse battery staple
password_confirmstringbodyyescorrect horse battery staple
termsbooleanbodyyesTrue

Request sample

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username": "Probe", "email": "probe@example.com", "password": "probe-pass-1", "password_confirm": "probe-pass-1", "terms": true}' 'https://example.com/invite/unknown-token'

Request JSON

{
  "email": "probe@example.com",
  "password": "probe-pass-1",
  "password_confirm": "probe-pass-1",
  "terms": true,
  "username": "Probe"
}

Response sample

{
  "data": {
    "username": "ada"
  },
  "ok": true,
  "redirect": "/"
}

API: Account

Session login, API key, notifications. No JWT, no OAuth.

GET /auth/login

Login page · auth public (guest) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/auth/login'

Response sample

{
  "errors": [],
  "next": "/admin"
}

POST /auth/login

Log in · auth public (guest) · negotiable

Sets an httponly session cookie (7 days, 30 with remember me).

Fields

NameTypeLocationRequiredExample
usernamestringbodyyes{{username}}
passwordpasswordbodyyesNone
rememberbooleanbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"username": "retoor"}' 'https://example.com/auth/login'

Request JSON

{
  "body": {
    "username": "retoor"
  }
}

Response sample

{
  "data": null,
  "ok": true,
  "redirect": "/admin"
}

POST /auth/logout

Log out · auth public (guest) · negotiable

Request sample

curl -X POST -H 'Accept: application/json' 'https://example.com/auth/logout'

Response sample

{
  "data": null,
  "ok": true,
  "redirect": "/"
}

GET /profile/api-key

View API key · auth member (Member) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/profile/api-key'

Response sample

{
  "api_key": "YOUR_API_KEY"
}

POST /profile/api-key/regenerate

Renew API key · auth member (Member) · negotiable

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/profile/api-key/regenerate'

Response sample

{
  "data": {
    "api_key": "..."
  },
  "ok": true,
  "redirect": "/profile/api-key"
}

POST /profile/avatar/regenerate

Renew avatar · auth member (Member) · negotiable

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/profile/avatar/regenerate'

Response sample

{
  "ok": true
}

GET /profile/keys

List SSH keys · auth member (Member) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/profile/keys'

Response sample

{
  "keys": []
}

POST /profile/keys

Add SSH key · auth member (Member) · negotiable

Registers one OpenSSH public key for git over SSH.

Fields

NameTypeLocationRequiredExample
namestringbodyyeslaptop
keystringbodyyesssh-ed25519 AAAA...

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/profile/keys'

Request JSON

{}

Response sample

{
  "data": {
    "fingerprint": "SHA256:...",
    "uid": "..."
  },
  "ok": true,
  "redirect": "/profile/keys"
}

POST /profile/keys/{uid}/delete

Delete SSH key · auth member (Member) · negotiable

Deletes one of your SSH keys.

Fields

NameTypeLocationRequiredExample
uidstringpathyes...

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/profile/keys/.../delete'

Request JSON

{
  "path": {
    "uid": "..."
  }
}

Response sample

{
  "data": {
    "uid": "..."
  },
  "ok": true,
  "redirect": "/profile/keys"
}

GET /notifications

Notifications · auth member (Member) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/notifications'

Response sample

{
  "notifications": [],
  "unread": 0
}

POST /notifications/read

Mark all read · auth member (Member) · negotiable

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/notifications/read'

Response sample

{
  "ok": true,
  "redirect": "/notifications"
}

GET /terms

Terms · auth public (guest) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/terms'

Response sample

{
  "title": "Terms"
}

POST /terms/accept

Accept terms · auth member (Member) · negotiable

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/terms/accept'

Response sample

{
  "ok": true,
  "redirect": "/"
}

GET /privacy

Privacy · auth public (guest) · negotiable

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/privacy'

Response sample

{
  "title": "Privacy"
}

API: Search

Three search modes over the rsearch backend: instant search, graded deepsearch, streamed deepresearch.

GET /search

Search page · auth public (guest) · negotiable

Fast multi-provider web search on submit.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/search'

Response sample

{
  "mode": "search"
}

GET /deepsearch

Deepsearch page · auth public (guest) · negotiable

Iterative research with graded sources and a written answer.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/deepsearch'

Response sample

{
  "mode": "deepsearch"
}

GET /deepresearch

Deepresearch page · auth public (guest) · negotiable

Live-streamed deep research with thinking trace and growing answer.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/deepresearch'

Response sample

{
  "mode": "deepresearch"
}

GET /search/api

Search API · auth public (guest) · negotiable

Proxies rsearch search. Query plus count, content, and cache flags. Answers results plus a telemetry envelope.

Fields

NameTypeLocationRequiredExample
qstringqueryyespython asyncio
countstringquerynoNone
contentstringquerynoNone
cachestringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/search/api?q=python+asyncio'

Request JSON

{
  "query": {
    "q": "python asyncio"
  }
}

Response sample

{
  "results": [],
  "telemetry": {}
}

GET /deepsearch/api

Deepsearch API · auth public (guest) · negotiable

Proxies rsearch deep research. Answers graded sources, markdown, rounds, plus a telemetry envelope. Runs fresh work unless cache=true replays a stored answer.

Fields

NameTypeLocationRequiredExample
qstringqueryyessodium battery state of the art
countstringquerynoNone
cachestringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/deepsearch/api?q=sodium+battery+state+of+the+art'

Request JSON

{
  "query": {
    "q": "sodium battery state of the art"
  }
}

Response sample

{
  "deep": {},
  "telemetry": {}
}

GET /deepsearch/stream

Deepsearch stream · auth public (guest) · negotiable

Server-sent stream: telemetry keep-alive while rsearch runs, then the result plus done, or error. The Deepsearch page always asks for cache=false.

Fields

NameTypeLocationRequiredExample
qstringqueryyessodium battery state of the art
countstringquerynoNone
cachestringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/deepsearch/stream?q=sodium+battery+state+of+the+art'

Request JSON

{
  "query": {
    "q": "sodium battery state of the art"
  }
}

Response sample

{
  "event": "result"
}

GET /deepresearch/stream

Deepresearch stream · auth public (guest) · negotiable

Server-sent stream: think, answer, sources, usage, telemetry, cost, then done or error.

Fields

NameTypeLocationRequiredExample
qstringqueryyesquantum computing breakthroughs

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/deepresearch/stream?q=quantum+computing+breakthroughs'

Request JSON

{
  "query": {
    "q": "quantum computing breakthroughs"
  }
}

Response sample

{
  "event": "think"
}

API: Scripted search

Research driven by a generated script: start a job, follow the live script and progress stream, and read the cited report.

GET /scriptedsearch

Scripted search page · auth public (guest) · negotiable

Question form, live script view, progress, report and recent runs.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/scriptedsearch'

Response sample

{
  "jobs": [],
  "mode": "scriptedsearch"
}

GET /scriptedsearch/jobs

List scripted searches · auth member (Member) · negotiable

The signed-in member's jobs, newest first.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/scriptedsearch/jobs'

Response sample

{
  "jobs": []
}

POST /scriptedsearch/jobs

Start scripted search · auth member (Member) · negotiable

Starts a background job for the question. One running job per member.

Fields

NameTypeLocationRequiredExample
querystringbodyyesWhich EU member states joined after 2004? List them with their capitals.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"query": ""}' 'https://example.com/scriptedsearch/jobs'

Request JSON

{
  "query": ""
}

Response sample

{
  "status": "running",
  "uid": ""
}

GET /scriptedsearch/jobs/{uid}

Scripted search job · auth member (Member) · negotiable

Status and, when finished, the parsed report, sources and script.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/scriptedsearch/jobs/{uid}'

Response sample

{
  "result": {},
  "status": "done"
}

POST /scriptedsearch/jobs/{uid}/cancel

Cancel scripted search · auth member (Member) · negotiable

Stops a running job; its events stay readable.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/scriptedsearch/jobs/{uid}/cancel'

Request JSON

{}

Response sample

{
  "status": "cancelled"
}

DELETE /scriptedsearch/jobs/{uid}

Delete scripted search · auth member (Member) · negotiable

Deletes a finished job with its events.

Request sample

curl -X DELETE -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/scriptedsearch/jobs/{uid}'

Response sample

{
  "ok": true
}

GET /scriptedsearch/jobs/{uid}/stream

Scripted search stream · auth member (Member) · negotiable

Server-sent events with ids for resume: budget, stage, requirements, script, exec, cost, site, results, step, warning, round, telemetry, result, error, done.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/scriptedsearch/jobs/{uid}/stream'

Response sample

{
  "event": "script"
}

GET /scriptedsearch/jobs/{uid}/report.md

Report download · auth member (Member) · none

Markdown report of a finished job.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/scriptedsearch/jobs/{uid}/report.md'

Response sample

{}

GET /scriptedsearch/jobs/{uid}/script.rrs

Script download · auth member (Member) · none

Research script of a finished job.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/scriptedsearch/jobs/{uid}/script.rrs'

Response sample

{}

API: Research workspace

Asynchronous research jobs: attach documents, start a multi-step agent run, follow its event stream, and read the cited report.

GET /research

Research workspace page · auth member (Member) · negotiable

Workspace with document tray, live run trace, report, charts and recent jobs.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/research'

Response sample

{
  "jobs": [],
  "mode": "research"
}

GET /research/jobs

List research jobs · auth member (Member) · negotiable

The signed-in member's started jobs, newest first.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/research/jobs'

Response sample

{
  "jobs": []
}

POST /research/jobs

New research job · auth member (Member) · negotiable

Creates a draft job that accepts documents until it starts.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/research/jobs'

Request JSON

{}

Response sample

{
  "status": "draft",
  "uid": ""
}

GET /research/jobs/{uid}

Research job · auth member (Member) · negotiable

Status, attached documents, and the final result when finished.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/research/jobs/{uid}'

Response sample

{
  "result": {},
  "status": "done"
}

POST /research/jobs/{uid}/documents

Attach document · auth member (Member) · negotiable

Multipart upload in field file. Accepts PDF, DOCX, TXT, MD, CSV, TSV, JSON, HTML, and ZIP archives of those.

Fields

NameTypeLocationRequiredExample
filefilebodyyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/research/jobs/{uid}/documents'

Request JSON

{}

Response sample

{
  "added": [],
  "rejected": []
}

DELETE /research/jobs/{uid}/documents/{document_uid}

Remove document · auth member (Member) · negotiable

Removes one document from a draft job.

Request sample

curl -X DELETE -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/research/jobs/{uid}/documents/{document_uid}'

Response sample

{
  "ok": true
}

POST /research/jobs/{uid}/start

Start research job · auth member (Member) · negotiable

Starts the agent on a draft job. Output preferences such as tone, format, tables and charts are read from the question.

Fields

NameTypeLocationRequiredExample
querystringbodyyesMarket analysis of European heat pump makers with a positioning matrix

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"query": "probe"}' 'https://example.com/research/jobs/{uid}/start'

Request JSON

{
  "query": "probe"
}

Response sample

{
  "status": "running"
}

POST /research/jobs/{uid}/cancel

Cancel research job · auth member (Member) · negotiable

Stops a running job; gathered events stay readable.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/research/jobs/{uid}/cancel'

Request JSON

{}

Response sample

{
  "status": "cancelled"
}

DELETE /research/jobs/{uid}

Delete research job · auth member (Member) · negotiable

Deletes a finished or draft job with its documents and events.

Request sample

curl -X DELETE -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/research/jobs/{uid}'

Response sample

{
  "ok": true
}

GET /research/jobs/{uid}/stream

Research job stream · auth member (Member) · negotiable

Server-sent events with ids for resume: status, plan, step, progress, review, warning, usage, telemetry, result, error, done.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/research/jobs/{uid}/stream'

Response sample

{
  "event": "step"
}

API: Skills

Agent skills: short descriptions on the list, full instructions plus file tree on each page.

GET /skills

Skills · auth public (guest) · negotiable

Every skill with its short description.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/skills'

Response sample

{
  "skills": [
    {
      "name": "deepresearch"
    }
  ]
}

GET /skills/{name}

Skill · auth public (guest) · negotiable

Long description, facts, file tree, and downloads.

Fields

NameTypeLocationRequiredExample
namestringpathyesdeepresearch

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/skills/deepresearch'

Request JSON

{
  "path": {
    "name": "deepresearch"
  }
}

Response sample

{
  "files": [],
  "skill": {
    "name": "deepresearch"
  }
}

GET /skills/{name}/download/zip

Download skill · auth public (guest) · negotiable

Whole package as ZIP, members prefixed with the skill name.

Fields

NameTypeLocationRequiredExample
namestringpathyesdeepresearch

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/skills/deepresearch/download/zip'

Request JSON

{
  "path": {
    "name": "deepresearch"
  }
}

Response sample

{
  "download": "deepresearch.zip"
}

GET /skills/{name}/files/{path}

Download skill file · auth public (guest) · negotiable

One packaged file. Images inline, everything else as attachment. Build artifacts and hidden files 404.

Fields

NameTypeLocationRequiredExample
namestringpathyesdeepresearch
pathstringpathyesSKILL.md

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/skills/deepresearch/files/SKILL.md'

Request JSON

{
  "path": {
    "name": "deepresearch",
    "path": "SKILL.md"
  }
}

Response sample

{
  "download": "SKILL.md"
}

API: Repos

Git hosting with visibility, roles, secrets, code search, and smart HTTP.

GET /repos

Repository list · auth public (guest) · negotiable

Accessible plus public repositories, newest first. Guests see public repositories only.

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos'

Response sample

{
  "repos": []
}

GET /repos/new

New repository form · auth member (Member) · negotiable

Create form for name, visibility, and short description.

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/new'

Response sample

{
  "repos": []
}

POST /repos

Repository creation · auth member (Member) · negotiable

Creates a repository. Names allow letters, digits, dot, _ and -, no leading dot.

Fields

NameTypeLocationRequiredExample
namestringbodyyesgarden
visibilitystringbodynosecret
descriptionstringbodynoTools for tending the garden.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos'

Request JSON

{}

Response sample

{
  "data": {
    "name": "garden",
    "uid": "..."
  },
  "ok": true,
  "redirect": "/repos/garden"
}

GET /repos/{name}

Repository page · auth public (guest) · negotiable

Files, rendered README, and clone URL. Public and hidden are readable by link, only public is listed, secret 404s for strangers.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

{
  "files": [],
  "repo": {
    "name": "garden"
  }
}

GET /repos/{name}/tree

Root listing · auth public (guest) · negotiable

Top-level entries of the default branch, same shape as the directory listing.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/tree'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

{
  "files": [],
  "path": "",
  "repo": {
    "name": "garden"
  }
}

GET /repos/{name}/tree/{path}

Directory listing · auth public (guest) · negotiable

Entries of one directory at the default branch with type, size, and whether the file opens in the site, depends on the browser, or is download only. Files redirect to the blob view.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
pathstringpathnosrc

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/tree/src'

Request JSON

{
  "path": {
    "name": "garden",
    "path": "src"
  }
}

Response sample

{
  "files": [
    {
      "kind": "code",
      "label": "Python",
      "name": "main.py",
      "path": "src/main.py",
      "support": "full",
      "url_path": "src/main.py",
      "viewable": true
    }
  ],
  "path": "src",
  "repo": {
    "name": "garden"
  }
}

GET /repos/{name}/blob/{path}

File view · auth public (guest) · negotiable

Numbered, highlighted source, rendered Markdown, inline images, video, audio, and PDF. Binary types show a download action. Directories redirect to the tree view.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
pathstringpathyessrc/main.py

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/blob/src/main.py'

Request JSON

{
  "path": {
    "name": "garden",
    "path": "src/main.py"
  }
}

Response sample

{
  "file": {
    "kind": "code",
    "language": "python"
  },
  "line_count": 1,
  "path": "src/main.py",
  "raw_url": "/repos/garden/raw/src/main.py",
  "text": "print(1)\n"
}

GET /repos/{name}/raw/{path}

Raw file · auth public (guest) · none

File bytes with the media type for images, video, audio, and PDF, text/plain for source, and attachment for binaries. Supports byte ranges and resolves Git LFS objects. Add download=1 to force an attachment.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
pathstringpathyesdocs/screenshot.png
downloadstringqueryno1

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/raw/docs/screenshot.png?download=1'

Request JSON

{
  "path": {
    "name": "garden",
    "path": "docs/screenshot.png"
  },
  "query": {
    "download": "1"
  }
}

Response sample

null

GET /repos/{name}/settings

Repository settings · auth member (Member) · negotiable

Visibility, default branch, short description and pull request settings. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/settings'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

{
  "repo": {
    "name": "garden"
  }
}

POST /repos/{name}/settings

Save settings · auth member (Member) · negotiable

Stores visibility, default branch, and short description. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
visibilitystringbodynosecret
default_branchstringbodynomain
descriptionstringbodynoTools for tending the garden.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/settings'

Request JSON

{}

Response sample

{
  "data": {
    "uid": "..."
  },
  "ok": true,
  "redirect": "/repos/garden/settings"
}

POST /repos/{name}/delete

Repository removal · auth member (Member) · negotiable

Soft delete. Needs repository.delete.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/delete'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

null

GET /repos/{name}/members

Repository members · auth member (Member) · negotiable

Grant table plus invite form. Needs repository.access.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/members'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

{
  "members": []
}

POST /repos/{name}/members

Grant access · auth member (Member) · negotiable

Grants a role or raw perms mask to a user uid or username. Needs repository.access.read or repository.access.write plus every bit granted.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
userstringbodyyeslezer
rolestringbodynoreader
permsintegerbodyno1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/members'

Request JSON

{}

Response sample

{
  "data": {
    "perms": 1,
    "user_uid": "..."
  },
  "ok": true,
  "redirect": "/repos/garden/members"
}

POST /repos/{name}/members/{user_uid}/revoke

Revoke access · auth member (Member) · negotiable

Removes a member grant. Needs repository.access.write. Last owner self-revoke is blocked.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
user_uidstringpathyes...

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/members/.../revoke'

Request JSON

{
  "path": {
    "name": "garden",
    "user_uid": "..."
  }
}

Response sample

null

GET /repos/{name}/secrets

Repository secrets · auth member (Member) · negotiable

Names and metadata only, values are never rendered. Needs repository.secrets.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/secrets'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

{
  "secrets": []
}

POST /repos/{name}/secrets

Store secret · auth member (Member) · negotiable

Seals a value under the per-repo key. Needs repository.secrets.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
namestringbodyyesDEPLOY_TOKEN
valuepasswordbodyyessecret-value

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/secrets'

Request JSON

{}

Response sample

{
  "data": {
    "name": "DEPLOY_TOKEN"
  },
  "ok": true,
  "redirect": "/repos/garden/secrets"
}

POST /repos/{name}/secrets/{secret_uid}/delete

Delete secret · auth member (Member) · negotiable

Deletes one sealed secret. Needs repository.secrets.delete.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
secret_uidstringpathyes...

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/secrets/.../delete'

Request JSON

{
  "path": {
    "name": "garden",
    "secret_uid": "..."
  }
}

Response sample

null

POST /repos/{name}/secrets/rotate

Rotate secrets · auth member (Member) · negotiable

Issues a new per-repo key and re-seals every secret. Needs repository.secrets.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/secrets/rotate'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

null

GET /git/{name}/info/refs

Git discovery · auth public (guest) · none

Smart HTTP advertisement. Upload-pack is public for public repos, receive-pack needs auth plus repository.write or push-to-create.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
servicestringqueryyesgit-upload-pack

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/git/garden/info/refs?service=git-upload-pack'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "service": "git-upload-pack"
  }
}

Response sample

null

POST /git/{name}/git-upload-pack

Git fetch · auth public (guest) · none

Smart HTTP fetch and clone body exchange.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X POST -H 'Accept: application/json' 'https://example.com/git/garden/git-upload-pack'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

null

POST /git/{name}/git-receive-pack

Git push · auth member (Member) · none

Smart HTTP push. Oversize pushes are rejected with 413 before unpack.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/git/garden/git-receive-pack'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

null

GET /repos/{name}/info/refs

Git discovery alias · auth public (guest) · none

Same smart HTTP advertisement as /git/{name}/info/refs, served on the page URL so git clients clone from /repos directly.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
servicestringqueryyesgit-upload-pack

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/info/refs?service=git-upload-pack'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "service": "git-upload-pack"
  }
}

Response sample

null

POST /repos/{name}/git-upload-pack

Git fetch alias · auth public (guest) · none

Same smart HTTP fetch exchange as /git/{name}/git-upload-pack, served on the page URL.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X POST -H 'Accept: application/json' 'https://example.com/repos/garden/git-upload-pack'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

null

POST /repos/{name}/git-receive-pack

Git push alias · auth member (Member) · none

Same smart HTTP push as /git/{name}/git-receive-pack, served on the page URL.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/git-receive-pack'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

null

POST /git/{name}/info/lfs/objects/batch

LFS batch · auth public (guest) · negotiable

Batch upload or download negotiation. Upload needs repository.write, download needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
operationstringbodyyesdownload
objectsstringbodyyes[{'oid': '0000000000000000000000000000000000000000000000000000000000000000', 'size': 5}]

Request sample

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{}' 'https://example.com/git/garden/info/lfs/objects/batch'

Request JSON

{}

Response sample

{
  "hash_algo": "sha256",
  "objects": [
    {
      "oid": "0000000000000000000000000000000000000000000000000000000000000000",
      "size": 5
    }
  ],
  "transfer": "basic"
}

GET /git/{name}/info/lfs/objects/{oid}

LFS object download · auth public (guest) · none

Streams one content-addressed object as application/octet-stream. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
oidstringpathyes0000000000000000000000000000000000000000000000000000000000000000

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/git/garden/info/lfs/objects/0000000000000000000000000000000000000000000000000000000000000000'

Request JSON

{
  "path": {
    "name": "garden",
    "oid": "0000000000000000000000000000000000000000000000000000000000000000"
  }
}

Response sample

{
  "encoding": "raw bytes",
  "oid": "0000000000000000000000000000000000000000000000000000000000000000",
  "size": 5
}

PUT /git/{name}/info/lfs/objects/{oid}

LFS object upload · auth member (Member) · none

Stores one object after verifying its sha256. Re-upload overwrites. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
oidstringpathyes0000000000000000000000000000000000000000000000000000000000000000

Request sample

curl -X PUT -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/git/garden/info/lfs/objects/0000000000000000000000000000000000000000000000000000000000000000'

Request JSON

{
  "path": {
    "name": "garden",
    "oid": "0000000000000000000000000000000000000000000000000000000000000000"
  }
}

Response sample

{
  "oid": "0000000000000000000000000000000000000000000000000000000000000000"
}

GET /git/{name}/info/lfs/locks

LFS lock list · auth member (Member) · negotiable

Lists file locks with cursor paging. Limit clamps to 1-100. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
limitintegerqueryno100
cursorstringqueryno

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/git/garden/info/lfs/locks?limit=100&cursor='

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "cursor": "",
    "limit": 100
  }
}

Response sample

{
  "locks": [
    {
      "id": "...",
      "locked_at": "2026-01-01T00:00:00+00:00",
      "owner": {
        "name": "lezer"
      },
      "path": "assets/sprite.bin"
    }
  ]
}

POST /git/{name}/info/lfs/locks

LFS lock creation · auth member (Member) · negotiable

Locks one repo-relative path. Conflict returns 409 with the existing lock. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
pathstringbodyyesassets/sprite.bin

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/git/garden/info/lfs/locks'

Request JSON

{}

Response sample

{
  "lock": {
    "id": "...",
    "locked_at": "2026-01-01T00:00:00+00:00",
    "owner": {
      "name": "lezer"
    },
    "path": "assets/sprite.bin"
  }
}

DELETE /git/{name}/info/lfs/locks/{id}

LFS unlock · auth member (Member) · negotiable

Deletes one lock. Non-owners pass force true. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
idstringpathyes...
forcebooleanbodynoFalse

Request sample

curl -X DELETE -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"force": false}' 'https://example.com/git/garden/info/lfs/locks/...'

Request JSON

{
  "body": {
    "force": false
  },
  "path": {
    "id": "...",
    "name": "garden"
  }
}

Response sample

{
  "lock": {
    "id": "...",
    "locked_at": "2026-01-01T00:00:00+00:00",
    "owner": {
      "name": "lezer"
    },
    "path": "assets/sprite.bin"
  }
}

POST /git/{name}/info/lfs/locks/verify

LFS lock verification · auth member (Member) · negotiable

Lists only the caller-owned locks with cursor paging. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
limitintegerqueryno100
cursorstringqueryno

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/git/garden/info/lfs/locks/verify?limit=100&cursor='

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "cursor": "",
    "limit": 100
  }
}

Response sample

{
  "locks": [
    {
      "id": "...",
      "locked_at": "2026-01-01T00:00:00+00:00",
      "owner": {
        "name": "lezer"
      },
      "path": "assets/sprite.bin"
    }
  ]
}

POST /repos/{name}/info/lfs/objects/batch

LFS batch on page URL · auth public (guest) · negotiable

Same batch negotiation as /git/{name}/info/lfs/objects/batch, served on the page URL for repos clones.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
operationstringbodyyesdownload
objectsstringbodyyes[{'oid': '0000000000000000000000000000000000000000000000000000000000000000', 'size': 5}]

Request sample

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/info/lfs/objects/batch'

Request JSON

{}

Response sample

{
  "hash_algo": "sha256",
  "objects": [
    {
      "oid": "0000000000000000000000000000000000000000000000000000000000000000",
      "size": 5
    }
  ],
  "transfer": "basic"
}

GET /repos/{name}/info/lfs/objects/{oid}

LFS object download on page URL · auth public (guest) · none

Same object stream as /git/{name}/info/lfs/objects/{oid}, served on the page URL. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
oidstringpathyes0000000000000000000000000000000000000000000000000000000000000000

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/info/lfs/objects/0000000000000000000000000000000000000000000000000000000000000000'

Request JSON

{
  "path": {
    "name": "garden",
    "oid": "0000000000000000000000000000000000000000000000000000000000000000"
  }
}

Response sample

{
  "encoding": "raw bytes",
  "oid": "0000000000000000000000000000000000000000000000000000000000000000",
  "size": 5
}

PUT /repos/{name}/info/lfs/objects/{oid}

LFS object upload on page URL · auth member (Member) · none

Same object store as /git/{name}/info/lfs/objects/{oid}, served on the page URL. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
oidstringpathyes0000000000000000000000000000000000000000000000000000000000000000

Request sample

curl -X PUT -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/info/lfs/objects/0000000000000000000000000000000000000000000000000000000000000000'

Request JSON

{
  "path": {
    "name": "garden",
    "oid": "0000000000000000000000000000000000000000000000000000000000000000"
  }
}

Response sample

{
  "oid": "0000000000000000000000000000000000000000000000000000000000000000"
}

GET /repos/{name}/info/lfs/locks

LFS lock list on page URL · auth member (Member) · negotiable

Same lock list as /git/{name}/info/lfs/locks, served on the page URL. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
limitintegerqueryno100
cursorstringqueryno

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/info/lfs/locks?limit=100&cursor='

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "cursor": "",
    "limit": 100
  }
}

Response sample

{
  "locks": [
    {
      "id": "...",
      "locked_at": "2026-01-01T00:00:00+00:00",
      "owner": {
        "name": "lezer"
      },
      "path": "assets/sprite.bin"
    }
  ]
}

POST /repos/{name}/info/lfs/locks

LFS lock creation on page URL · auth member (Member) · negotiable

Same lock creation as /git/{name}/info/lfs/locks, served on the page URL. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
pathstringbodyyesassets/sprite.bin

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/info/lfs/locks'

Request JSON

{}

Response sample

{
  "lock": {
    "id": "...",
    "locked_at": "2026-01-01T00:00:00+00:00",
    "owner": {
      "name": "lezer"
    },
    "path": "assets/sprite.bin"
  }
}

DELETE /repos/{name}/info/lfs/locks/{id}

LFS unlock on page URL · auth member (Member) · negotiable

Same unlock as /git/{name}/info/lfs/locks/{id}, served on the page URL. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
idstringpathyes...
forcebooleanbodynoFalse

Request sample

curl -X DELETE -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"force": false}' 'https://example.com/repos/garden/info/lfs/locks/...'

Request JSON

{
  "body": {
    "force": false
  },
  "path": {
    "id": "...",
    "name": "garden"
  }
}

Response sample

{
  "lock": {
    "id": "...",
    "locked_at": "2026-01-01T00:00:00+00:00",
    "owner": {
      "name": "lezer"
    },
    "path": "assets/sprite.bin"
  }
}

POST /repos/{name}/info/lfs/locks/verify

LFS lock verification on page URL · auth member (Member) · negotiable

Same verification as /git/{name}/info/lfs/locks/verify, served on the page URL. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
limitintegerqueryno100
cursorstringqueryno

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/info/lfs/locks/verify?limit=100&cursor='

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "cursor": "",
    "limit": 100
  }
}

Response sample

{
  "locks": [
    {
      "id": "...",
      "locked_at": "2026-01-01T00:00:00+00:00",
      "owner": {
        "name": "lezer"
      },
      "path": "assets/sprite.bin"
    }
  ]
}

POST /{owner}/{repo}.git/info/lfs/objects/batch

LFS batch alias · auth public (guest) · negotiable

GitHub-compatible batch alias. The owner segment is ignored, repos resolve by flat name.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
operationstringbodyyesdownload
objectsstringbodyyes[{'oid': '0000000000000000000000000000000000000000000000000000000000000000', 'size': 5}]

Request sample

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{}' 'https://example.com/someone/garden.git/info/lfs/objects/batch'

Request JSON

{}

Response sample

{
  "hash_algo": "sha256",
  "objects": [
    {
      "oid": "0000000000000000000000000000000000000000000000000000000000000000",
      "size": 5
    }
  ],
  "transfer": "basic"
}

GET /{owner}/{repo}.git/info/lfs/objects/{oid}

LFS object download alias · auth public (guest) · none

GitHub-compatible object download alias. The owner segment is ignored.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
oidstringpathyes0000000000000000000000000000000000000000000000000000000000000000

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/someone/garden.git/info/lfs/objects/0000000000000000000000000000000000000000000000000000000000000000'

Request JSON

{
  "path": {
    "oid": "0000000000000000000000000000000000000000000000000000000000000000",
    "owner": "someone",
    "repo": "garden"
  }
}

Response sample

{
  "encoding": "raw bytes",
  "oid": "0000000000000000000000000000000000000000000000000000000000000000",
  "size": 5
}

PUT /{owner}/{repo}.git/info/lfs/objects/{oid}

LFS object upload alias · auth member (Member) · none

GitHub-compatible object upload alias. The owner segment is ignored. Needs repository.write.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
oidstringpathyes0000000000000000000000000000000000000000000000000000000000000000

Request sample

curl -X PUT -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/someone/garden.git/info/lfs/objects/0000000000000000000000000000000000000000000000000000000000000000'

Request JSON

{
  "path": {
    "oid": "0000000000000000000000000000000000000000000000000000000000000000",
    "owner": "someone",
    "repo": "garden"
  }
}

Response sample

{
  "oid": "0000000000000000000000000000000000000000000000000000000000000000"
}

GET /{owner}/{repo}.git/info/lfs/locks

LFS lock list alias · auth member (Member) · negotiable

GitHub-compatible lock list alias. The owner segment is ignored. Needs repository.read.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
limitintegerqueryno100
cursorstringqueryno

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/someone/garden.git/info/lfs/locks?limit=100&cursor='

Request JSON

{
  "path": {
    "owner": "someone",
    "repo": "garden"
  },
  "query": {
    "cursor": "",
    "limit": 100
  }
}

Response sample

{
  "locks": [
    {
      "id": "...",
      "locked_at": "2026-01-01T00:00:00+00:00",
      "owner": {
        "name": "lezer"
      },
      "path": "assets/sprite.bin"
    }
  ]
}

POST /{owner}/{repo}.git/info/lfs/locks

LFS lock creation alias · auth member (Member) · negotiable

GitHub-compatible lock creation alias. The owner segment is ignored. Needs repository.write.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
pathstringbodyyesassets/sprite.bin

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/someone/garden.git/info/lfs/locks'

Request JSON

{}

Response sample

{
  "lock": {
    "id": "...",
    "locked_at": "2026-01-01T00:00:00+00:00",
    "owner": {
      "name": "lezer"
    },
    "path": "assets/sprite.bin"
  }
}

DELETE /{owner}/{repo}.git/info/lfs/locks/{id}

LFS unlock alias · auth member (Member) · negotiable

GitHub-compatible unlock alias. The owner segment is ignored. Needs repository.write.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
idstringpathyes...
forcebooleanbodynoFalse

Request sample

curl -X DELETE -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"force": false}' 'https://example.com/someone/garden.git/info/lfs/locks/...'

Request JSON

{
  "body": {
    "force": false
  },
  "path": {
    "id": "...",
    "owner": "someone",
    "repo": "garden"
  }
}

Response sample

{
  "lock": {
    "id": "...",
    "locked_at": "2026-01-01T00:00:00+00:00",
    "owner": {
      "name": "lezer"
    },
    "path": "assets/sprite.bin"
  }
}

POST /{owner}/{repo}.git/info/lfs/locks/verify

LFS lock verification alias · auth member (Member) · negotiable

GitHub-compatible lock verification alias. The owner segment is ignored. Needs repository.read.

Fields

NameTypeLocationRequiredExample
ownerstringpathyessomeone
repostringpathyesgarden
limitintegerqueryno100
cursorstringqueryno

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/someone/garden.git/info/lfs/locks/verify?limit=100&cursor='

Request JSON

{
  "path": {
    "owner": "someone",
    "repo": "garden"
  },
  "query": {
    "cursor": "",
    "limit": 100
  }
}

Response sample

{
  "locks": [
    {
      "id": "...",
      "locked_at": "2026-01-01T00:00:00+00:00",
      "owner": {
        "name": "lezer"
      },
      "path": "assets/sprite.bin"
    }
  ]
}

GET /repos/search

Global code search · auth member (Member) · negotiable

Search page across every readable repository.

Fields

NameTypeLocationRequiredExample
qstringquerynomigrate

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/search?q=migrate'

Request JSON

{
  "query": {
    "q": "migrate"
  }
}

Response sample

{
  "query": "",
  "scope": "repos-global"
}

GET /repos/{name}/search

Repository code search · auth member (Member) · negotiable

Search page scoped to one repository. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
qstringquerynomigrate

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/search?q=migrate'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "q": "migrate"
  }
}

Response sample

{
  "query": "",
  "scope": "repos-one"
}

GET /repos/search/api

Global code search JSON · auth member (Member) · negotiable

JSON hits plus telemetry. Query q is capped at 500 chars, count clamps to 1-100.

Fields

NameTypeLocationRequiredExample
qstringquerynomigrate
countintegerqueryno10

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/search/api?q=migrate&count=10'

Request JSON

{
  "query": {
    "count": 10,
    "q": "migrate"
  }
}

Response sample

{
  "results": [],
  "scope": "repos-global",
  "telemetry": {}
}

GET /repos/{name}/search/api

Repository code search JSON · auth member (Member) · negotiable

JSON hits plus telemetry scoped to one repository. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
qstringquerynomigrate
countintegerqueryno10

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/search/api?q=migrate&count=10'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "count": 10,
    "q": "migrate"
  }
}

Response sample

{
  "results": [],
  "scope": "repos-one",
  "telemetry": {}
}

GET /repos/search/stream

Global code search stream · auth member (Member) · negotiable

Server-sent stream with result, telemetry, and done events.

Fields

NameTypeLocationRequiredExample
qstringquerynomigrate

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/search/stream?q=migrate'

Request JSON

{
  "query": {
    "q": "migrate"
  }
}

Response sample

{
  "event": "done"
}

GET /repos/{name}/search/stream

Repository code search stream · auth member (Member) · negotiable

Server-sent stream scoped to one repository. Needs repository.read.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
qstringquerynomigrate

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/search/stream?q=migrate'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "q": "migrate"
  }
}

Response sample

{
  "event": "done"
}

GET /repos/{name}/branches

Branches · auth public (guest) · negotiable

Active branches: default, branches with open pull requests, and branches with commits in the last 90 days.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/branches'

Request JSON

{
  "path": {
    "name": "garden"
  }
}

Response sample

{
  "branches": [],
  "stale_branches": 0
}

GET /repos/{name}/compare

Compare branches · auth member (Member) · negotiable

Merge check, commits and diff between a base and a head branch, plus the creation form.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
basestringquerynomain
headstringquerynofeature

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/garden/compare?base=main&head=feature'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "base": "main",
    "head": "feature"
  }
}

Response sample

{
  "check": {
    "status": "mergeable"
  }
}

GET /repos/pulls

All pull requests · auth member (Member) · negotiable

Pull requests across every readable repository with status, review, draft, merge, author and involvement filters.

Fields

NameTypeLocationRequiredExample
statestringquerynoNone
involvedstringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/repos/pulls?state=open&involved=authored'

Request JSON

{
  "query": {
    "involved": "authored",
    "state": "open"
  }
}

Response sample

{
  "counts": {},
  "pulls": []
}

GET /repos/{name}/pulls

Pull requests · auth public (guest) · negotiable

Pull requests of one repository with status tabs and filters.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
statestringquerynoNone
reviewstringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/pulls?state=open&review=any'

Request JSON

{
  "path": {
    "name": "garden"
  },
  "query": {
    "review": "any",
    "state": "open"
  }
}

Response sample

{
  "counts": {
    "open": 0
  },
  "pulls": []
}

POST /repos/{name}/pulls

Create pull request · auth member (Member) · negotiable

Opens a pull request from head into base. Needs repository.write.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
basestringbodyyesmain
headstringbodyyesfeature
titlestringbodyyesAdd feature
bodystringbodynoNone
reviewersstringbodynocleo

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls'

Request JSON

{}

Response sample

{
  "ok": true,
  "redirect": "/repos/garden/pulls/1"
}

GET /repos/{name}/pulls/{number}

Pull request · auth public (guest) · negotiable

Conversation, commits or files changed of one pull request, with merge box and reviewers.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
tabstringquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/pulls/1?tab=conversation'

Request JSON

{
  "path": {
    "name": "garden",
    "number": 1
  },
  "query": {
    "tab": "conversation"
  }
}

Response sample

{
  "pull": {
    "number": 1
  }
}

POST /repos/{name}/pulls/{number}/edit

Edit pull request · auth member (Member) · negotiable

Changes title, description or base branch. Author or writers, open pull requests only.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
titlestringbodynoNone
bodystringbodynoNone
basestringbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/edit'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/wip

Toggle work in progress · auth member (Member) · negotiable

Adds or removes the work-in-progress title prefix.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/wip'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/close

Close pull request · auth member (Member) · negotiable

Closes an open pull request. Author or writers.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/close'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/reopen

Reopen pull request · auth member (Member) · negotiable

Reopens a closed pull request when both branches exist.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/reopen'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/comments

Comment · auth member (Member) · negotiable

Adds a conversation comment; action=close closes the pull request as well.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
bodystringbodynoNone
actionstringbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/comments'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/comments/{comment_uid}/edit

Edit comment · auth member (Member) · negotiable

Edits your own comment.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
comment_uidstringpathyesNone
bodystringbodyyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/comments/{comment_uid}/edit'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/comments/{comment_uid}/delete

Delete comment · auth member (Member) · negotiable

Deletes your own comment; repository administrators may delete any comment.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
comment_uidstringpathyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/comments/{comment_uid}/delete'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/code-comments

Line comment · auth member (Member) · negotiable

Comments on a diff line as a single comment or as part of your pending review; thread replies to a conversation.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
bodystringbodyyesNone
modestringbodynoNone
pathstringbodynoNone
sidestringbodynoNone
lineintegerbodynoNone
threadstringbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/code-comments'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/threads/{thread_uid}/{action}

Resolve conversation · auth member (Member) · negotiable

Resolves or unresolves a conversation. Author, writers and official reviewers.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
thread_uidstringpathyesNone
actionstringpathyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/threads/{thread_uid}/{action}'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/reviews

Submit review · auth member (Member) · negotiable

Submits a review: approve, comment or reject (request changes). Authors cannot approve or reject their own pull request.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
typestringbodyyesNone
bodystringbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/reviews'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/reviews/discard

Discard pending review · auth member (Member) · negotiable

Deletes your pending review and its pending comments.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/reviews/discard'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/reviews/{review_uid}/dismiss

Dismiss review · auth member (Member) · negotiable

Dismisses an approval or change request with a message. Repository administrators only.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
review_uidstringpathyesNone
messagestringbodyyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/reviews/{review_uid}/dismiss'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/reviewers

Request review · auth member (Member) · negotiable

Requests or re-requests a review from a user who can read the repository.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
userstringbodyyescleo

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/reviewers'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/reviewers/{user_uid}/remove

Remove review request · auth member (Member) · negotiable

Removes a pending review request.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
user_uidstringpathyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/reviewers/{user_uid}/remove'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/viewed

Mark file viewed · auth member (Member) · negotiable

Marks or unmarks a changed file as viewed for yourself.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
pathstringbodyyesNone
viewedbooleanbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/viewed'

Request JSON

{}

Response sample

null

GET /repos/{name}/pulls/{number}/check

Merge status · auth public (guest) · negotiable

Current merge status, advisory warnings and assisted merge availability.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/pulls/1/check'

Request JSON

{
  "path": {
    "name": "garden",
    "number": 1
  }
}

Response sample

{
  "pull": {
    "merge_status": "mergeable"
  },
  "warnings": []
}

POST /repos/{name}/pulls/{number}/delete-branch

Delete head branch · auth member (Member) · negotiable

Deletes the head branch of a closed or merged pull request when it has no new commits.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/delete-branch'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/restore-branch

Restore head branch · auth member (Member) · negotiable

Recreates a deleted head branch from refs/pull/N/head.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/restore-branch'

Request JSON

{}

Response sample

null

POST /repos/{name}/pulls/{number}/merge

Merge pull request · auth member (Member) · negotiable

Starts a merge job: merge, rebase, rebase-merge, squash, fast-forward-only or manually-merged; assisted=1 resolves conflicts with the assistant. Writers may merge their own pull requests.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
stylestringbodynoNone
titlestringbodynoNone
messagestringbodynoNone
commitstringbodynoNone
delete_branchbooleanbodynoNone
assistedbooleanbodynoNone
acknowledgedstringbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/merge'

Request JSON

{}

Response sample

{
  "data": {
    "job": "..."
  },
  "ok": true
}

POST /repos/{name}/pulls/{number}/update

Update branch · auth member (Member) · negotiable

Merges the base branch into the head branch when that merge is clean.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/update'

Request JSON

{}

Response sample

null

GET /repos/{name}/pulls/{number}/merge/jobs/{job_uid}

Merge job · auth public (guest) · negotiable

State of a merge job.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
job_uidstringpathyesNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/pulls/1/merge/jobs/{job_uid}'

Request JSON

{
  "path": {
    "name": "garden",
    "number": 1
  }
}

Response sample

{
  "job": {
    "status": "running"
  }
}

GET /repos/{name}/pulls/{number}/merge/jobs/{job_uid}/stream

Merge job stream · auth public (guest) · negotiable

Server-sent events: line, phase, telemetry, state, cleanup, error, result, done.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
job_uidstringpathyesNone
afterintegerquerynoNone

Request sample

curl -X GET -H 'Accept: application/json' 'https://example.com/repos/garden/pulls/1/merge/jobs/{job_uid}/stream'

Request JSON

{
  "path": {
    "name": "garden",
    "number": 1
  }
}

Response sample

{
  "event": "done"
}

POST /repos/{name}/pulls/{number}/merge/jobs/{job_uid}/cancel

Cancel merge job · auth member (Member) · negotiable

Cancels a running merge job; cleanup always runs. Starter or repository administrators.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
numberintegerpathyes1
job_uidstringpathyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/pulls/1/merge/jobs/{job_uid}/cancel'

Request JSON

{}

Response sample

null

POST /repos/{name}/settings/pulls

Pull request settings · auth member (Member) · negotiable

Allowed merge styles, default style, branch deletion default, manual merge, merge detection and assisted merging.

Fields

NameTypeLocationRequiredExample
namestringpathyesgarden
merge_stylesstringbodynoNone
default_merge_stylestringbodynoNone
assisted_mergebooleanbodynoNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{}' 'https://example.com/repos/garden/settings/pulls'

Request JSON

{}

Response sample

null

POST /admin/users/{uid}/login-as

Impersonate account · auth admin (Admin) · negotiable

Switches into the account with a stacked session. Senior administrators and deactivated accounts are refused.

Fields

NameTypeLocationRequiredExample
uidstringpathyesNone

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/admin/users/{uid}/login-as'

Response sample

{
  "data": {
    "impersonated_by": {
      "uid": "..."
    },
    "uid": "..."
  },
  "ok": true,
  "redirect": "/"
}

POST /admin/login-as/exit

Exit impersonation · auth admin (Admin) · negotiable

Deletes the impersonated session and restores the administrator cookie.

Request sample

curl -X POST -H 'Accept: application/json' -H 'X-API-KEY: YOUR_API_KEY' 'https://example.com/admin/login-as/exit'

Response sample

{
  "data": {
    "impersonated_by": null
  },
  "ok": true,
  "redirect": "/admin/users"
}