API

An API HTTP taobh thiar de gach cliant Nessie, agus conas fíordheimhniú a dhéanamh air.

Cad é an API

Tá API HTTP amháin ag Nessie. Is cliaint dá chuid iad an feidhmchlár riaracháin gréasáin, na cliaint macOS agus iOS agus an daemon executor cianda, agus níl aon rud is féidir leo a dhéanamh inrochtana ar bhealach ar bith eile. Is API JSON é os cionn freastalaí Fastify, ní GraphQL é, agus níl fo-thacar “poiblí” ar leith aige: an dromchla a ghlaonn do scripteanna féin is é an dromchla a ghlaonn an táirge.

Níl aon chuid leagana sa chosán. Tá gach bealach faoi /api, ach amháin an deireadh-phointe isteach MCP ag POST /mcp agus cúpla doiciméad fionnachtana faoi /.well-known/. Bainistear comhoiriúnacht trí réimsí a chur leis amháin, ionas gur féidir le cliant nach aithníonn réimse áirithe neamhaird a dhéanamh air agus leanúint ar aghaidh ag obair.

Bun-URL

Is féinóstáilte é Nessie, mar sin is é an bun-URL ná an bunús (origin) ar a bhfreastalaíonn d’imscaradh an API. Socraíonn an t-oibreoir é mar NESSIE_API_PUBLIC_URL, agus an luach céanna is ea a úsáideann an API nuair a bhíonn URL absalóideach de chuid féin le déanamh. Ar an gcás a reáchtálaimid, is é sin https://api.nessie.works; freagraíonn cás forbartha a thosaítear le pnpm dev ar http://localhost:5454.

Is bunús difriúil é feidhmchlár riaracháin an ghréasáin ón API, mar sin tá cliaint bhrabhsálaí faoi liosta ceadaithe CORS (NESSIE_CORS_ORIGINS). Ní bhíonn aon bhunús ag iarratais ó script nó ó fhreastalaí le seiceáil, agus ní théann an liosta i bhfeidhm orthu.

Fíordheimhniú

Iompraíonn gach iarratas lasmuigh de thacar beag bealaí atá poiblí d’aon ghnó comhartha rochtana sa cheanntásc caighdeánach:

Authorization: Bearer <token>

Comhartha JWT sínithe é an comhartha a eisíonn an API. Tá sé gearrshaolach — tríocha nóiméad de réir réamhshocraithe (NESSIE_AUTH_TOKEN_TTL) — agus is é an t-aon chreidiúint a chuireann glaoiteoirí coitianta i láthair riamh. Níl aon eochair phearsanta fhadsaolach API ag Nessie. Má theastaíonn uait go nglaonn script ar an API, logálann sé isteach ar an mbealach céanna is a logálann brabhsálaí duine, agus nuaíonn sé a chomhartha de réir mar a théann sé ar aghaidh.

Comhartha a fháil

Cruthaíonn POST /api/auth/session seisiún. Freagraíonn sé leis an gcomhartha rochtana agus aitheantas an ghlaoiteora, agus socraíonn sé an comhartha athnuachana mar fhianán ar leith HTTP-only.

Braitheann an bealach a chruthaíonn tú cé thú féin ar an gcaoi a imscaradh an ionstáil. Glacann ionstáil atá ag rith i mód local le ríomhphost agus pasfhocal. Ar ionstáil hosted nó selfHosted, diúltaítear logáil isteach le pasfhocal go díreach, le 403 PASSWORD_AUTH_DISABLED, agus is é an soláthraí aitheantais cumraithe an t-aon bhealach isteach — ionas nach bhfásfaidh cuntas riamh cosán aitheantais dara, níos laige, taobh leis.

Logáil isteach trí sholáthraí aitheantais

Is malartú cód údaraithe OAuth le PKCE é an aon-logáil isteach (SSO), i dtrí chéim. Is é UnlikeOtherAI soláthraí aitheantais féin Nessie, agus tá sé de chúram aige an struchtúr eagraíochta agus foirne a léiríonn an ionstáil. Tá an malartú thíos ar an gcruth céanna do sholáthraí cumraithe ar bith.

1. Liostaíonn GET /api/auth/providers na soláthraithe a nglacann an ionstáil seo leo. Do gach ceann acu, tugann sé providerId, lipéad, agus an mbíonn an leathanach logála isteach ag atreorú chuige go huathoibríoch.
2. GET /api/auth/providers/:providerId/authorize, le codeChallenge, redirectUri agus state mar pharaiméadair cheiste, freagraíonn sé le { data: { authorizeUrl } }. Seol an duine ansiúd.
3. Cuireann an soláthraí an duine ar ais chuig do redirectUri le cód. Seol an cód sin ar ais mar POST /api/auth/session le { providerId, code, codeVerifier, redirectUri } — tá na ceithre cinn riachtanach le chéile, agus tugann tacar neamhiomlán 400 EXTERNAL_AUTH_INCOMPLETE.

Seisiún a athnuachan

Ní bhíonn an comhartha athnuachana i gcorp freagra go deo. Socraítear mar fhianán HTTP-only é darb ainm nessie_refresh, teoranta don chosán /api/auth, le saolré tríocha lá de réir réamhshocraithe (NESSIE_AUTH_REFRESH_TOKEN_TTL). Má ghlaonn tú POST /api/auth/refresh leis an bhfianán sin, úsáidtear an fianán, eisítear comhartha rochtana nua agus socraítear fianán nua ina áit — rothlaíonn na comharthaí, mar sin ní bhíonn comhartha goidte bailí ach go dtí go nuaíonn an cliant fíor an chéad uair eile.

Coinníonn brabhsálaí a bhfuil logáilte isteach i roinnt cuntas fianán den chineál sin do gach logáil isteach, darb ainm nessie_refresh_<slot>, agus luann sé an ceann a bhaineann leis an iarratas leis an gceanntásc x-nessie-account-slot. Cliant nach seolann an ceanntásc sin, baineann sé le nessie_refresh, agus is leor sin do chliant líne ordaithe.

Mar sin teastaíonn cófra fianán ó chliant líne ordaithe. Le curl is é --cookie-jar ar ghlao na logála isteach agus --cookie ar an athnuachan, mar atá sa sampla oibre thíos.

Cad a sheiceáiltear ar gach iarratas

Ní seiceáil síniú amháin é fíordheimhniú. Sula rith aon láimhseálaí, seiceálann an API síniú agus dul in éag an chomhartha, deimhníonn sé nach ndearnadh an seisiún a athghairm (de réir leagan an chomhartha ar fud an úsáideora agus de réir aitheantais an tseisiúin aonair), agus luchtaíonn sé ballraíocht an ghlaoiteora san eagraíocht a luann an comhartha. Is 403 a bheidh ar bhallraíocht dhíghníomhachtaithe. Nuair a bhíonn an eagraíocht fóinteáilte ag soláthraí aitheantais seachtrach, seiceáiltear stádas reatha an ghlaoiteora leis an soláthraí sin ar an iarratas seachas é a léamh ón gcomhartha, ionas go stopann rochtain a baintear ag obair láithreach, seachas ag an gcéad dul in éag eile.

Creidiúintí nach comharthaí seisiúin iad

Tá dhá chreidiúint iompróra eile ann, agus ní heochair ghinearálta ceachtar acu. Glactar le creidiúint gléis gutha ach amháin ar na bealaí glaonna gutha, agus glactar le creidiúint rochtana gníomhaire ach amháin ar an deireadh-phointe MCP. Diúltaítear do cheachtar acu in aon áit eile le 403 a ainmníonn an chreidiúint, agus ní thriailtear arís é mar sheisiún níos laige — féach MCP agus uirlisí ceangailte le haghaidh conas a eisítear creidiúint an ghníomhaire.

Cuntas an fhreagra

Is réad é gach freagra rathúil le heochair data. Níl aon eagar nocht ná aon phá-ualach ag leibhéal uachtarach an fhreagra, ionas nach gá do chliant riamh idirdhealú a dhéanamh ar an gcruth:

{
  "data": { "id": "3f1c…", "label": "engineering" }
}

Cuireann pointí deiridh liosta réad meta go taobh leis. Ní chuirtear aon ní eile leis ag leibhéal uachtarach riamh.

Úsáideann teipeanna cruth amháin freisin, cibé rud a tháinig ón am:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A message needs content or at least one attachment",
    "field": "body",
    "details": { "formErrors": [], "fieldErrors": {} }
  }
}

Is é code an chuid inléite ag ríomhaire, agus is air sin ba cheart duit brainse; is do dhuine é message. Bíonn field agus details i láthair nuair a bhíonn an teip ar leith go leor le suíomh a aimsiú. Bíonn earráid fhreastalaí neamhláimhsithe i gcónaí mar 500 INTERNAL_ERROR le teachtaireacht sheasta — déantar téacs na bunearráide a logáil, ní thugtar ar ais riamh é, toisc go bhféadfadh sonraí iarratais a bheith greamaithe de ar a bhealach amach.

Na códanna earráide is coitianta

Leathanaigh

Leathanaíonn liostaí le cúrsóir eochair doléite, ní le fritháireamh — cuirtear sraitheanna isteach fad is a léann duine, agus le fritháireamh déanann an dara leathanach athrá ar thaifead a thaispeáin an chéad leathanach cheana, gan aon fhógra.

Glactar le trí pharaiméadar cheiste: cursor, limit agus direction (forward nó backward). Is é 25 an leathanach réamhshocraithe agus 100 an uasteorainn; ní dhiúltaítear luach níos mó, ach teorannaítear chuig an uasteorainn é. Cuireann pointí deiridh a dhéanann sórtáil nó scagadh sort, order agus téacs saor in aisce q leis.

Insíonn meta an leathanaigh cá bhfuil tú:

{
  "data": [ … ],
  "meta": {
    "hasMore": true,
    "nextCursor": "2026-09-12T08:31:44.005Z|8b2f…",
    "prevCursor": null,
    "total": 134
  }
}

Is fíor araon nextCursor agus prevCursor: is rialuithe iad Roimhe agus Ar aghaidh a bhfuil súil ag duine leo. Tá siad doléite — is é an freastalaí a chódaíonn a eochair sórtála féin iontu, agus briseann cliant a pháirseálann nó a thógann ceann acu an nóiméad a athraíonn liosta a ord. Is minic a bhíonn total i láthair ar liostaí, ach fágtar amach é áit nach bhfuil comhaireamh brí léi, mar shampla i dtorthaí cuardaigh rangaithe.

Teorainneacha rátaí

Tá teorainneacha in aghaidh fuinneoga seasta agus cuirtear i bhfeidhm iad sula léitear corp an iarratais fiú. Is 429 é iarratas diúltaithe, leis an gcód RATE_LIMITED agus ceanntásc Retry-After i soicindí.

Is de réir seoladh IP a dhéantar an chuid is mó de na buicéid. Coinníonn na buicéid atá íogair do dhintiúir — logáil isteach, athnuachan, athdhearbhú pasfhocail agus scríbhinní creidiúna MCP — cuntaisteoir in aghaidh an chuntais freisin, agus diúltaíonn siad nuair a bhuaileann ceann ar bith acu an teorainn. Mar sin, buaileann seoladh amháin a spreagann go leor cuntas agus cuntas amháin a ionsaítear ó go leor seoladh. Is é an réamhshocrú le haghaidh logála isteach 10 iarracht in aghaidh an IP agus 5 in aghaidh an seoladh ríomhphoist in gach deich nóiméad; is 60 in aghaidh an nóiméid é teachtaireacht a phostáil; agus is 60 in aghaidh an nóiméid na scríbhinní faoi /api/agents. Is féidir gach tairseach a chumrú in aghaidh an imscaradh, mar sin ná glac leis na luachanna seo mar chonradh, ach mar na réamhshocruithe a sheoltar. Níl seiceálacha sláinte ná sruthanna fíor-ama faoi theorainn.

Fíor-ama

Ní hé an bealach ceart comhrá a leanúint liosta a athlódáil de shíor. Tá trí chríochphointe sruthaithe ann ina ionad:

• GET /api/events/stream — imeachtaí a sheoltar ón bhfreastalaí do gach rud is féidir leis an duine logáilte isteach a fheiceáil.
• GET /api/threads/:threadId/stream — imeachtaí a sheoltar ón bhfreastalaí do shnáithe amháin. Urramaíonn sé Last-Event-ID, mar sin leanann athnascadh ar aghaidh in ionad atosú.
• GET /api/activity — WebSocket a iompraíonn sruth na gníomhaíochta.

Ní féidir le brabhsálaithe ceanntásca a shocrú ar láimhdeachas WebSocket, mar sin glacann an bealach WebSocket an comhartha rochtana freisin mar pharaiméadar cheiste ?token=. Is é sin an t-aon áit ina mbaineann comhartha le URL; glacann gach bealach eile leis an gceanntásc.

Teaghlaigh acmhainní

Tá i bhfad níos mó ná míle críochphointe ann, rud atá i bhfad ró-mhór le liostáil. Grúpálann siad ina dteaghlaigh iad, agus nuair a bhíonn réimír teaghlaigh ar eolas agat, is intuartha na bealaí aonair — bailiúchán ag an réimír, taifead faoi, agus gníomhartha ainmnithe mar fho-chosáin POST.

Déantar cearta a fhorfheidhmiú de réir bealaigh, ní de réir teaghlaigh. Go ginearálta: is dromchlaí iad an rian iniúchta, an leabhar costais, rialacha polasaí agus plean rialaithe an tátail d’úinéirí agus do riarthóirí eagraíochta, agus is oscailte do gach ball iad comhráite, tionscadail, eolas agus ceadanna, ach teoranta de réir an rud is féidir leis an mball sin a fheiceáil i ndáiríre.

Samplaí oibre

Logáil isteach agus coinnigh an fianán athnuachana

Ar ionstáil local le pasfhocal. Tagann an comhartha rochtana ar ais sa chorp; téann an comhartha athnuachana isteach sa chófra fianán.

curl -sS https://api.example.com/api/auth/session \
  --cookie-jar nessie.cookies \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"…"}'

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
    "me": {
      "user": {
        "id": "1d4e…",
        "email": "ada@example.com",
        "displayName": "Ada Lovelace",
        "roleIds": ["owner"],
        "superAdmin": false
      },
      "session": {
        "sessionId": "9c07…",
        "issuedAt": "2026-09-16T09:00:00.000Z",
        "expiresAt": "2026-09-16T09:30:00.000Z"
      },
      "context": {
        "organizationId": "5a81…",
        "projectId": "7b12…",
        "teamId": "2e60…",
        "channelId": null,
        "bootstrapMode": false
      },
      "auth": {
        "providerId": "local",
        "providerType": "local-bootstrap",
        "autoRedirectToSso": false
      }
    }
  }
}

Nuair a rachaidh an comhartha rochtana in éag, malartaigh an fianán le haghaidh ceann nua:

curl -sS -X POST https://api.example.com/api/auth/refresh \
  --cookie nessie.cookies --cookie-jar nessie.cookies

Is é an freagra an cruth céanna { token, me }, agus tá an comhartha athnuaite sa chófra fianán anois.

Liostaigh na cainéil is féidir leat a fheiceáil

curl -sS https://api.example.com/api/channels \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "8b2f…",
      "label": "engineering",
      "type": "standard",
      "visibility": "public",
      "projectId": "…",
      "projectName": "Platform",
      "teamId": "…",
      "defaultThreadId": "c41a…",
      "unreadCount": 3,
      "lastMessageAt": "2026-09-15T18:22:07.441Z",
      "viewerCanManage": true
    }
  ]
}

Cuir ?teamId=… leis chun foireann amháin a chúngú, nó ?includeArchived=true chun cainéil chartlainne a áireamh. Is é defaultThreadId an rud a phostálann tú ar aghaidh.

Postáil teachtaireacht

Teastaíonn content nó aon cheangaltán uaslódáilte amháin ar a laghad le teachtaireacht. Seol Idempotency-Key agus réitíonn iarracht athdhéanta go dtí an teachtaireacht a chruthaigh an chéad iarracht, seachas cóip dara a phostáil.

curl -sS https://api.example.com/api/threads/c41a…/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0f9c2d16-8f4a-4c1e-9a77-6b0d4f2e1a53' \
  -d '{"content":"Deploying the migration now."}'

Is 201 é freagra teachtaireachta nua:

{
  "data": {
    "message": {
      "id": "d70e…",
      "threadId": "c41a…",
      "role": "user",
      "content": "Deploying the migration now.",
      "createdAt": "2026-09-16T09:04:11.882Z"
    },
    "pendingAgentInvites": []
  }
}

Freagraíonn athsheoladh den eochair chéanna le 200 agus leis an teachtaireacht bhunaidh, agus pendingAgentInvites folamh, toisc gur rinne an chéad iarracht an fógairt agus an seoladh a chuireann an t-aicme síos orthu cheana.

Tá dhá dhiúltú ar an mbealach seo a bhfuil sé tairbheach iad a láimhseáil go sainráite. Diúltaítear d’ábhar a sháraíonn teorainn fhada na comhrá le 413 MESSAGE_TOO_LARGE, agus is é an freagra ceart an téacs a uaslódáil mar chomhad. Diúltaítear d’ábhar a bhreathnaíonn ar struchtúr mar chreidiúint le 422 SECRET_INTERCEPTED — diúltaíonn an freastalaí sula stóráiltear, sula seoltar agus sula logáiltear an teachtaireacht, agus is sa /api/secrets ba cheart an chreidiúint a bheith.