DEVELOPERS

API

Agents and scripts call Gitwork over HTTPS with a Bearer API key. Create a key in the dashboard (shown once), then send Authorization: Bearer gw_live_… on every /api/v1 request.

DashboardAPI keys

Quick start

export GITWORK_API_KEY=gw_live_…
export GITWORK_API_BASE=https://gitwork.getuigen.dev

curl -s "$GITWORK_API_BASE/api/v1/me" \
  -H "Authorization: Bearer $GITWORK_API_KEY"

Public website routes like /api/lineup do not require a key. Agent access should use /api/v1 only.

Scopes

Each key carries scopes. Missing a required scope returns 403. New keys get all scopes by default.

scout:readScout cards, country lineups, and Ask match/discover
profile:readRead your claimed profile
profile:writeUpdate availability, bio, contact, and rates
requests:readList hire inbox and read message threads
requests:writeReply on hire threads as the developer

Endpoints

Expand an endpoint for request body (when needed) and a sample response.

GET

/api/v1/me

Who this key belongs to, and which scopes it has.

any valid key

Response

{
  "userId": "…",
  "githubLogin": "darula-hpp",
  "scopes": ["scout:read", "profile:read", "profile:write", "requests:read", "requests:write"],
  "keyId": "…"
}

GET

/api/v1/card/[username]

Scout a GitHub profile into a Gitwork player card.

scout:read

Rate-limited (~60/min per key).

Response

{
  "login": "torvalds",
  "name": "Linus Torvalds",
  "overall": 94,
  "position": "CB",
  "family": "Anchor",
  "stats": { "pac": 72, "sho": 68, "pas": 88, "dri": 80, "def": 95, "phy": 91 },
  "country": "us",
  "topLanguage": "C"
  // …full card fields
}

GET

/api/v1/lineup?country=bw

National Starting XI for a country code (ISO / Gitwork flag code).

scout:read

Query param country is required. Rate-limited.

Response

{
  "countryCode": "bw",
  "lineup": [
    { "id": "ST", "label": "ST", "card": { "login": "…", "overall": 82 }, "claim": null }
    // …RW, CAM, CM, CDM, CB, LW
  ],
  "cards": [ /* ranked pool */ ],
  "source": "search",
  "attempted": 45,
  "placed": 7
}

POST

/api/v1/ask/match

Match a natural-language scout question to a template + recipe.

scout:read

Pass template.recipe (and vars) into /ask/discover. Rate-limited.

Request body

{
  "query": "top typescript developers in botswana"
}

Response

{
  "template": {
    "id": "…",
    "title": "Top language developers in a country",
    "queryTemplate": "…",
    "recipe": { "filters": […], "sort": { "by": "overall", "dir": "desc" }, "limit": 45 }
  },
  "vars": { "country": "bw", "language": "TypeScript" },
  "missing": [],
  "score": 0.82
}

POST

/api/v1/ask/discover

Run live discovery for a country using a recipe (usually from match).

scout:read

Rate-limited. Can take longer while profiles are scouted.

Request body

{
  "countryCode": "bw",
  "recipe": {
    "filters": [{ "field": "country", "op": "eq", "value": "bw" }],
    "sort": { "by": "overall", "dir": "desc" },
    "limit": 45
  },
  "vars": { "country": "bw" }
}

Response

{
  "cards": [ /* Card[] */ ],
  "source": "search",
  "attempted": 30,
  "message": null
}

GET

/api/v1/claim

Read the claim for the key owner (availability, contact, rates, bio).

profile:read

Response

{
  "claim": {
    "githubLogin": "darula-hpp",
    "available": true,
    "contactEmail": "dev@example.com",
    "contactUrl": null,
    "rateMin": 50,
    "rateMax": 80,
    "bio": "…",
    "displayCountry": "bw"
  }
}

PATCH

/api/v1/claim

Update your claim. Only send fields you want to change.

profile:write

Request body

{
  "available": true,
  "bio": "Open to contract work",
  "contactEmail": "dev@example.com",
  "rateMin": 50,
  "rateMax": 80,
  "displayCountry": "bw"
}

Response

{
  "claim": { /* updated PublicClaim */ }
}

GET

/api/v1/requests/inbox

Hire threads where you are the target developer.

requests:read

Response

{
  "requests": [
    {
      "id": "…",
      "title": "Need a TypeScript engineer",
      "targetGithubLogin": "darula-hpp",
      "status": "open",
      "messages": [ /* optional preview */ ]
    }
  ]
}

GET

/api/v1/requests/[id]/messages

Full message thread for a request you are the developer on.

requests:read

Response

{
  "messages": [
    {
      "id": "…",
      "requestId": "…",
      "authorRole": "client",
      "body": "Hi, are you free next month?",
      "createdAt": "2026-07-14T00:00:00.000Z"
    }
  ]
}

POST

/api/v1/requests/[id]/messages

Reply on a hire thread as the developer.

requests:write

Request body

{
  "body": "Yes, I have availability in August."
}

Response

{
  "message": {
    "id": "…",
    "requestId": "…",
    "authorRole": "developer",
    "body": "Yes, I have availability in August.",
    "createdAt": "2026-07-14T00:00:00.000Z"
  }
}

Create an API key Home