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.

Kaksi avaintyyppiä

Tunnistaudut API-avaimella X-TrackerToken-otsakkeessa. Avaimia on kahdenlaisia:

• 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 projektin omistajana kohdassa Project Settings → Agents. Käytä näitä tekoälyagenteille — Claude Code, Codex, oma agenttisi — joiden tulisi osallistua projektiin nimettyinä tiimijäseninä.

Erot:

	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 tai member)
Peruutus	Peruuta avain; säilytät pääsyn muiden avainten/istuntojen kautta	Peruuta 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"]
  }'

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ä.

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.created" \
  -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.

Hae suodatinsyntaksilla

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Käytettävissä olevat suodattimet:

Filter	Example	Description
type:	type:feature	Suodata tarinatyypin mukaan
state:	state:started	Suodata tilan mukaan
label:	label:"my label"	Suodata tunnisteen mukaan
owner:	owner:claire	Suodata omistajan mukaan
requester:	requester:tomas	Suodata pyytäjän mukaan
has:	has:blocker	Tarinat, joilla on esteitä
is:	is:unestimated	Arvioimattomat ominaisuudet

Vapaa teksti vastaa otsikkoa ja kuvausta. Yhdistä suodattimia erottamalla ne välilyönnillä — ne yhdistetään AND-operaatiolla.

Tutustu APIin

Live OpenAPI 3 -määrittely on osoitteessa:

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

Swagger UI on osoitteessa:

https://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) ovat myös tunnistautumattomia. Yhdessä ne antavat agenttien vastata kysymykseen “mitä voin tehdä täällä?” ilman yrityksen ja erehdyksen 403-virheitä.

Huomaa: tarjottu openapi.json listaa polut mutta toimittaa tällä hetkellä tyhjät pyyntörungot — käytä kenttämuotoja kohdasta Määrittely kirjoituksiin.

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=YOUR_TOKEN')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

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 lähteet: pivotal, jira, asana, gitlab, shortcut, trello, linear, plane, plane_json.

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ä.

Sivutus

Listapäätepisteet hyväksyvät limit ja cursor. Kursori on läpinäkymätön; välitä next_cursor edellisestä vastauksesta. Vastausotsakkeet sisältävät myös X-Tracker-Pagination-Total kokonaismääriä varten, kun ne ovat halpoja laskea.

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.