API-opas

East Agile Trackerin API on suunniteltu agenteille yhtä lailla kuin ihmisille. Kaiken minkä voit tehdä käyttöliittymässä, voit tehdä APIn yli — ja muutamia asioita, joita käyttöliittymä ei paljasta, on sielläkin.

Tämä opas vie sinut nollasta “backlogin skriptaamiseen” alle kymmenessä minuutissa. Täydellisen päätepisteviittauksen löydät kohdasta API-määrittely.

Kolme tunnistetyyppiä

Tunnistaudut avaimella X-TrackerToken-otsakkeessa. On kaksi avaintyyppiä, jotka luot itse, ja kolmas, jonka MCP-asiakas hankkii puolestasi:

Käyttäjäavaimet (ea_user_…) — Toimivat sinuna. Luo ne kohdassa Account Settings → API Keys. Käytä näitä henkilökohtaisiin skripteihin, CLI-työkaluihin ja integraatioihin.
Agenttiavaimet (ea_agent_…) — Toimivat nimettynä agenttina yhdessä projektissa. Luo ne kohdassa Project Settings → Agents. Käytä näitä tekoälyagenteille — Claude Code, Codex, oma agenttisi — joiden tulisi osallistua projektiin nimettyinä tiimijäseninä.
MCP-tokenit (ea_mcp_…) — OAuth 2.1 -käyttöoikeustokeneita, jotka myönnetään MCP-asiakkaalle (Claude, IDE) sen jälkeen kun olet hyväksynyt sen suostumussivulla. Ne toimivat sinuna, ja voit peruuttaa ne kohdassa Account Settings → Connected apps.

Kertaluonteinen ikkuna henkilökohtaisen API-avaimen luomisen jälkeen tilin asetuksissa; avain on peitetty tässä kuvassa

Agent-välilehden avaimenluontilomake, jossa on nimi ja valittuna rooli member, asetusohjeiden alla

Erot niiden kahden välillä, jotka luot itse:

	User key	Agent key
Laajuus	Kaikki projektisi	Yksi tietty projekti
Identiteetti tarkastuslokissa	Sinun nimesi	Agentin nimi
Rooli	Roolisi kussakin projektissa	Asetetaan avaimen luonnin yhteydessä (viewer, member tai manager — ei koskaan avaimen luoneen jäsenen omaa roolia korkeampi)
Peruutus	Peruuta avain; säilytät pääsyn muiden avainten/istuntojen kautta	Peruuta tai kierrätä avain; agentti menettää pääsyn välittömästi
Parhaiten sopii	Henkilökohtainen automaatio, skriptit	Tekoälyagentit, jotka tulisi erottaa sinusta historiassa

Authorization: Bearer … toimii myös, jos pidät enemmän tästä otsaketyylistä.

Hello, API

Hae projektisi:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Tai agenttiavaimella listaa projekti, johon se on rajattu:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

API on JSON-pohjainen, REST-henkinen, versioitu polkuun /api/v1/. Samat muodot ihmisille ja agenteille.

Luo projekti

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

Vastaus sisältää project_id:n ja kaikki palvelimen soveltamat oletukset (arviointiasteikko, valmis-tila jne.).

Luo tarina

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate on skaalan arvon nimike merkkijonona — "3", tai "13" Fibonacci -skaalassa — koska sen on osuttava projektin skaalan pisteeseen. JSON-luku hylätään.

Siirrä tarina elinkaaren läpi

Siirtymäpäätepiste validoi pyydetyn siirron ja palauttaa sallitut seuraavat tilat virhetilanteessa:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

Kenttä on to (ei to_state). Jos siirto on laiton — vaikkapa yritit hypätä tilasta unstarted suoraan tilaan accepted — vastaus on 422 invalid_transition jäsennellyin virhetiedoin:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] }
}

Tämä on yksi niistä pienistä asioista, jotka tekevät APIsta agenttiystävällisen: agentti voi lukea details.allowed ja valita oikean seuraavan siirron raapimatta tekstiä.

rejected on siirtymäpäätepisteen lopputila. Palauttaaksesi hylätyn tarinan työn alle käytä POST …/stories/{sid}/restart; POST …/stories/{sid}/reject on verbimuoto toimitetun tarinan hylkäämiselle.

Kommentoi tarinaa

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

Kommentti kohdistetaan sille, joka omistaa API-avaimen — jos kyseessä on agenttiavain, kommentin tekijä on agentti.

Idempotentit kirjoitukset

Jokainen kirjoituspäätepiste hyväksyy Idempotency-Key-otsakkeen. Toista sama avain samalla rungolla, saat saman vastauksen takaisin. Toista sama avain eri rungolla, saat virheen 409 idempotency_conflict:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

Tämä on ratkaisevaa uudelleenyrityssilmukoissa toimiville agenteille — kaadu kesken kirjoituksen, yritä uudelleen samalla avaimella, ei kahdentuneita tarinoita.

Massasiirtymät

Siirrä useita tarinoita kerralla. Jokainen tarina arvioidaan itsenäisesti; yksi laiton siirto ei kaada muita.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

Seuraa tapahtumavirtaa

Agenteille, jotka haluavat reagoida siihen mitä ihmiset tekevät, pollaa tapahtumapäätepistettä:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Vastaus on kursorisivutettu tapahtumavirta, joka sisältää toimijan, resurssin ja muutoksen. Jokaisella tapahtumalla on ID; välitä viimeisin näkemäsi ID arvona since jatkaaksesi siitä mihin jäit. Ei webhookkeja, ei raapimista, ei menetettyjä tapahtumia. Virta vaatii member-roolin — katsoja saa vastauksen 403.

Haku

GET /projects/{id}/search?q=<query> suorittaa tehokkaan kokoteksti- ja rakennehaun projektin tarinoista. Kyselykieli on mallinnettu GitHubin issue-haun määreiden mukaan — joten syntaksi, jonka sinä (tai tekoälyagentti) jo tunnet GitHubista, toimii enimmäkseen sellaisenaan.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

Vastaus on JSON-kuori, jossa tarinat on järjestetty osuvuuden mukaan:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total on osumien kokonaismäärä, ei sivun koko. Sivuta parametreilla limit (oletus 50, enintään 1000) ja offset; järjestä parametrilla sort=relevance (oletus), created, created_asc, updated tai state.

Kielioppi

Vapaa teksti osuu tarinan otsikkoon, viitteeseen ja kuvaukseen (kokotekstihaku sanavartaloiden perusteella, osuvuusjärjestyksessä). Kääri tarkka ilmaus "lainausmerkkeihin".
Määreet ovat muotoa field:value. Erota vaihtoehdot pilkulla (OR kentän sisällä): type:bug,chore. Erota määreet välilyönnillä (AND niiden välillä).
Kiellä mikä tahansa termi tai määre etumerkillä -: -label:wontfix.
Välit päivämäärille ja pisteille: päätepisteet mukaan lukien a..b tai avoin väli >x / <x.

Määreet

Qualifier	Example	Matches
`type:`	`type:bug,chore`	tarinatyyppi tai -tyypit
`state:`	`state:started,finished`	työnkulun tila tai tilat
`label:`	`label:"my label"`	tunniste
`epic:`	`epic:"Checkout"`	eepin tarinat
`priority:`	`priority:p1`	prioriteetti
`points:`	`points:3` · `points:1..5` · `points:>3`	arvion arvo tai väli
`iteration:`	`iteration:42`	iteraation id
`created:` `updated:` `started:` `completed:` `release:`	`created:2026-05-01..2026-06-01` · `updated:>2026-06-01`	päivämäärä tai väli (päivän tarkkuudella); `release:` on tarinan julkaisupäivä
`owner:` `requester:` `follower:` `reviewer:` `commenter:` `mention:`	`owner:claire` · `owner:@me`	henkilö nimen tai sähköpostin perusteella — jäsenet ja agentit, myös `mention:`; `@me` olet sinä
`has:blocker`	`has:blocker`	tarinalla on avoin este
`is:`	`is:unestimated` · `is:icebox` · `is:backlog` · `is:blocked`	lippu

mywork: on alias määreelle owner: — mywork:me tarkoittaa samaa kuin owner:@me. Vanhempi scheduled:-määre on poistettu käytöstä ja ohitetaan hiljaisesti; käytä määrettä release:.

Pilkku-OR (type:bug,chore) koskee fasettimääreitä; henkilömääreet (owner: requester: follower: reviewer: commenter: mention:) ottavat yhden arvon.

Esimerkit

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

Sama kyselymerkkijono ohjaa sekä taulun hakukenttää (joka avaa live-tulossarakkeen) että tätä APIa — yksi kielioppi niin ihmisille kuin agenteillekin. Kommenttien, tehtävien ja esteiden sisällön haku on tiekartalla; tällä hetkellä vapaa teksti kattaa tarinan oman otsikon, viitteen ja kuvauksen.

Tutustu APIin

Live OpenAPI 3 -määrittely on osoitteessa:

https://api.eastagiletracker.com/api/v1/openapi.json

Swagger UI on osoitteessa:

https://api.eastagiletracker.com/api/v1/docs/

/openapi.json ja /docs ovat tunnistautumattomia — agentti voi lukea sopimuksen ennen kuin sillä on avain. Kun sillä on avain, /api/v1/meta (joka vaatii kelvollisen avaimen) palauttaa sen identiteetin ja tarinatyyppikohtaisen siirtymägraafin; viitedatahaut (/story_types, /story_states, /effort_scales, /priority_scales) ovat myös tunnistautumattomia. Yhdessä ne antavat agenttien vastata kysymykseen “mitä voin tehdä täällä?” ilman yrityksen ja erehdyksen 403-virheitä.

Tarjottu openapi.json sisältää kirjoituspäätepisteiden pyyntörunkojen skeemat, mukaan lukien kunkin kentän maxLength-arvon, joten asiakas voi validoida ennen lähettämistä. Määrittely tiivistää samat muodot.

WebSocket-ohjaus

Interaktiiviseen automaatioon — sisäänkirjautuneen selainistunnon ohjaamiseen skriptistä tai käyttöliittymän etäohjaamiseen tutoriaaleja varten — on WebSocket-kanava:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

token on selainistunnon JWT, ei API-avain — ea_user_*- tai ea_agent_*-avain hylätään ennen yhteyden päivitystä (upgrade). Useimmat käyttäjät eivät koskaan tarvitse tätä; se on olemassa tapauksiin, joissa REST ei riitä.

Tuo toisesta trackerista

Jos skriptaat massamigraatiota:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

Tuetut tiedostolähteet: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json, eat (East Agile Trackerin oma vienti — edestakainen muoto). Multipart-päätepiste toimii synkronisesti ja vastaa tuloslukemilla.

GitHub tuo APIsta tiedoston sijaan, JSON-päätepisteen kautta — ei file, vain repositorion koordinaatit:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

JSON-päätepiste on asynkroninen: se vastaa 202 ja { "import_id", "status" }, ja kyselet päätepistettä GET /projects/{id}/imports/{import_id}, kunnes työ saavuttaa tilan done tai failed. Projektissa ajetaan vain yksi tuonti kerrallaan — toinen kutsu, kun tuonti on jo käynnissä, palauttaa 409 import_already_running. Koko silmukka työn edistymiskenttineen on sivulla Täytä projekti GitHub-repositoriosta.

token on pyynnössä valinnainen, mutta itse haku todentautuu aina — se kulkee GitHubin GraphQL-rajapinnan kautta, jossa ei ole anonyymia tasoa. Jätä token pois, niin palvelin käyttää alustatokeniaan: vain julkiset repositoriot, jaettu kaikkien kutsujien kesken ja hylätty koodilla import_github_shared_quota_low, kun sen GraphQL-budjetti laskee alle 500 pisteen. Yksityinen repositorio tai asennus, jolle ei ole määritetty alustatokenia (import_github_no_token), vaatii omasi. Kumpi token tahansa on käytössä, sitä käytetään vain ylävirran GitHub-kutsuihin, eikä sitä koskaan tallenneta tai kaiuteta takaisin. Kaikki yksityiskohdat, mukaan lukien GitHubin todentamaton 60 pyynnön REST-katto, ovat sivulla Täytä projekti GitHub-repositoriosta.

Kuiva-ajon esikatselu. Lisää "dry_run": true (JSON) tai -F "dry_run=true" (multipart) mihin tahansa lähteeseen. Tuonti jäsentää, ratkaisee ja poistaa duplikaatit täsmälleen kuten oikea ajo, palauttaa samat tuloslukemat (imported, skipped, errors, unmatched) ja peruu sitten kaiken — mitään ei kirjoiteta. JSON-päätepisteessä lukemat saapuvat kyseltävään työhön, oli kyseessä kuiva-ajo tai ei.

Rajat. Latausrunko on rajattu 10 MiB:iin ja yksittäinen tuonti 5 000 tarinaan; kumman tahansa ylittäminen on 400 ilman että mitään kirjoitetaan. Tiedoston uudelleentuonti on turvallista — jo tuodut rivit (tunnistettuna lähde-id:llä) ohitetaan, ei kahdenneta.

Vie projekti

Mikä tahansa projektirooli voi listata muodot; yhden lataaminen on vain omistajille:

# Rekisteröidyt export-muodot: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Lataa yksi muoto (eat on täystarkkuuksinen edestakainen CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

Vaihtomuotojen id:t: eat, jira, pivotal, shortcut, trello, asana, gitlab, linear, plane, plane_json, sekä asiakirjamuodot pdf ja docx. Jokainen liite on ladattavissa yhtenä zip-tiedostona osoitteesta GET /projects/{id}/export/attachments.

Virhemuoto

Kaikki virheet ovat JSON-muotoa ja sisältävät vähintään:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

Monet virhevastaukset sisältävät myös details-objektin — details.fields (taulukko virheellisten kenttien nimistä) virheessä validation_failed, ja details.allowed (kenttien from/to ohella) virheessä 422 invalid_transition. Käytä niitä. 429 rate_limited -vastaus sisältää Retry-After-otsakkeen ja saman JSON-kuoren.

Sivutus

Listapäätepisteet hyväksyvät limit ja cursor. Kursori on läpinäkymätön; välitä next_cursor edellisestä vastauksesta. limit-katto on päätepistekohtainen — 200 tarinoille, kommenteille ja projekteille, 500 tapahtumille, 1000 haulle ja tarkastuslokille. Tavallinen (ei-kursori-) lista, jonka vastaus jouduttiin katkaisemaan, kertoo sen otsakkeissa: X-Tracker-Pagination-Truncated, -Limit, -Offset ja -Next-Offset, jonka välität takaisin muodossa offset= seuraavaa sivua varten. Kokonaismääräotsaketta ei ole.

Mitä seuraavaksi

API-määrittely — Jokainen päätepiste, jokainen verbi, jokainen muoto.
Käyttöohjeet → Agentit — Käyttöliittymäpuoli: agenttiavainten luonti, agenttien nimeäminen, peruuttaminen.
Johdanto — APIn taustalla olevat käsitteet: tarinat, tilat, iteraatiot, nopeus, agentit.