API-opas

Aloita East Agile Trackerin REST-rajapinnan käyttö: käyttäjä- ja agenttiavaimet, storyjen luonti ja siirto, idempotentit kirjoitukset, haku, tapahtumat ja sivutus.

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 → Agent. 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 → API Keys → 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://api.eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Tai agenttiavaimella listaa projekti, johon se on rajattu:

curl https://api.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://api.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 palvelimen soveltamat iteraatio-oletukset (iteration_start_day, initial_velocity, iteration_length_weeks); GET /projects/{id} palauttaa kaikki asetukset.

Luo tarina

curl -X POST https://api.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://api.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, ja päätepiste hylkää myös arvon to: "rejected". Hylkää toimitettu tarina kutsulla POST …/stories/{sid}/reject; palauta hylätty tarina työn alle kutsulla POST …/stories/{sid}/restart, joka toimii niin kauan kuin tarina on nykyisessä iteraatiossa.

Kommentoi tarinaa

curl -X POST https://api.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

Kirjoituspäätepisteet hyväksyvät Idempotency-Key-otsakkeen (liitteiden latauksia lukuun ottamatta). Toista sama avain samalla rungolla 24 tunnin sisällä, saat saman vastauksen takaisin. Toista sama avain eri rungolla, saat virheen 409 idempotency_conflict:

curl -X POST https://api.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. Vastausta 5xx, 401, 403, 404 tai 429 ei koskaan välimuistiteta, joten uudelleenyritys sellaisen jälkeen suorittaa pyynnön uudelleen.

Massasiirtymät

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

curl -X POST https://api.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://api.eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since_id=$LAST_EVENT_ID&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Vastaus on { items, next_since_id, next_cursor }: jokainen tapahtuma sisältää toimijan, resurssin ja muutoksen. Tallenna next_since_id ja välitä se seuraavassa kyselyssä arvona since_id jatkaaksesi siitä mihin jäit (since hyväksytään vanhempana aliaksena). 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://api.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, kun kyselyssä on vapaata tekstiä, ja muuten taulun järjestykseen:

{ "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ä (agenttiavaimella avaimen luonut jäsen)
`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-05-31 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.

Tuo toisesta trackerista

Jos skriptaat massamigraatiota:

curl -X POST https://api.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://api.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. Tuontitiedosto on rajattu 10 MiB:iin ja 5 000 tarinaan (400 import_too_large / import_too_many_records, mitään ei kirjoiteta); GitHub-tuonnilla ei ole tarinakattoa. 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 vaatii manager-roolin:

# Rekisteröidyt export-muodot: { id, name, content_type, drops, includes_archived }
curl https://api.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://api.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 tarkastuslokille; haku sivuttaa parametreilla limit (≤ 1000) ja offset. 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.