API:n yleiskatsaus

Diaformin API antaa omalle koodillesi ja AI-agenteillesi pääsyn keräämääsi palautteeseen: projekteihin, keskusteluihin AI-yhteenvetoineen ja koko litterointeineen sekä AI-raportteihin. Sen avulla voit analysoida vastauksia omalla agentillasi, syöttää tietoja tietovarastoon tai käynnistää automaatioita.

Yhteyden voi muodostaa kahdella tavalla, ja molemmat käyttävät samaa API-avainta ja palauttavat samat tiedot:

• REST-API. JSON HTTPS:n yli skripteille, taustajärjestelmille ja automaatiotyökaluille.
• MCP-palvelin. AI-agenteille, kuten Claude Code, Codex tai Cursor. Agentti saa API:n työkaluina, joita se voi kutsua suoraan. Katso MCP-palvelin.

Mitä voit tehdä#

Jos haluat tiedon keskustelun päättymisestä ilman, että haet tietoja API:sta toistuvasti, käytä webhookeja.

Ennen kuin aloitat#

Tarvitset kaksi asiaa:

1. Pro-, Business- tai Enterprise-paketin.
2. API-avaimen. Omistajat ja ylläpitäjät luovat avaimia kohdassa Asetukset → Yleiset → API-avaimet.

Luo avain klikkaamalla Uusi API-avain, anna sille nimi ja klikkaa Luo avain. Klikkaa Uusi API-avaimesi -ikkunassa Kopioi ja sitten Olen tallentanut avaimen. Diaform näyttää avaimen vain kerran.

Avaimet ovat muotoa dia_org_live_ ja sen perässä 32 merkkiä. Ne eivät vanhene. Kullakin organisaatiolla voi olla enintään 10 avainta. Poista avain käytöstä klikkaamalla Mitätöi ja sitten Mitätöi API-avain. Kaikki, mikä käyttää avainta, lakkaa toimimasta saman tien.

Todennus#

Lähetä avain bearer-tokenina jokaisessa pyynnössä:

Authorization: Bearer dia_org_live_...

Avain voi lukea organisaationsa kaikki projektit riippumatta projektien käyttöoikeusasetuksista. Pidä se palvelimellasi tai agenttisi määrityksissä äläkä koskaan laita sitä selain- tai sovelluskoodiin. Näiden ohjeiden esimerkit lukevat sen ympäristömuuttujasta DIAFORM_API_KEY.

Perus-URL ja käytännöt#

https://diaform.io/api/v1

• Pyynnöt ja vastaukset ovat JSON-muotoisia. Kenttien nimet ovat muotoa snake_case.
• ID:t ovat UUID-tunnisteita. Aikaleimat ovat ISO 8601 -merkkijonoja UTC-ajassa.
• Kenttä, jolla ei ole arvoa, on null. Sitä ei koskaan jätetä pois.
• API kutsuu haastattelijaa projektiksi, kuten hallintapaneelikin. Projektin ID on ID, joka tulee projektin hallintapaneelin URL-osoitteessa kohdan /agents/ jälkeen ja julkisessa linkissä kohdan /c/ jälkeen.
• Hallintapaneelin Esikatselu-tilassa aloitettuja keskusteluja ei koskaan palauteta.

Tee ensimmäinen pyyntösi#

Listaa projektisi:

curl "https://diaform.io/api/v1/projects" \
  -H "Authorization: Bearer $DIAFORM_API_KEY"

Hae sitten yhden projektin valmiit keskustelut:

curl -G "https://diaform.io/api/v1/projects/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d/conversations" \
  -H "Authorization: Bearer $DIAFORM_API_KEY" \
  --data-urlencode "status=completed" \
  --data-urlencode "limit=50"

Sivutus#

Listaavat päätepisteet palauttavat uusimmat kohteet ensin tässä muodossa:

{
  "data": [],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTA1LTA3VDEyOjAwOjAwLjEyMzQ1NiswMDowMCIsIjBmOGQ0M2EyIl0"
}

Hae seuraava sivu toistamalla pyyntö samoilla suodattimilla ja asettamalla cursor-parametrin arvoksi next_cursor. Viimeisellä sivulla has_more on false ja next_cursor on null.

async function listAllConversations(projectId) {
  const conversations = [];
  let cursor = null;

  do {
    const url = new URL(
      `https://diaform.io/api/v1/projects/${projectId}/conversations`,
    );
    url.searchParams.set("status", "completed");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.DIAFORM_API_KEY}` },
    });
    if (!response.ok) throw new Error((await response.json()).error);

    const page = await response.json();
    conversations.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);

  return conversations;
}

Virheet#

Virheet käyttävät tavallisia HTTP-tilakoodeja ja palauttavat JSON-vastauksen, jossa on luettava error-viesti ja pysyvä code, jonka mukaan koodisi voi toimia:

{
  "error": "No project with this ID exists in your organization.",
  "code": "not_found"
}

400-vastauksessa on lisäksi details, jossa on yksi merkintä kutakin virheellistä kenttää kohden:

{
  "error": "The request has invalid parameters.",
  "code": "invalid_request",
  "details": [
    { "field": "limit", "message": "Too big: expected number to be <=100" }
  ]
}

Toisen organisaation ID palauttaa 404, samoin kuin ID, jota ei ole olemassa.

Pyyntörajat#

Kukin API-avain voi tehdä 120 pyyntöä minuutissa lukupäätepisteisiin ja MCP-palvelimeen yhteensä. Rajan ylittävät pyynnöt palauttavat 429 ja otsakkeen Retry-After: 60. Kukin sivu palauttaa enintään 100 kohdetta.

Anna nämä ohjeet agentillesi#

Jokaisella ohjesivulla on Kopioi sivu -painike, joka kopioi sivun Markdown-muodossa valmiiksi AI-agentille liitettäväksi. Jokainen sivu on saatavilla myös pelkkänä Markdownina ja koko API-viite yhtenä tiedostona:

https://diaform.io/api/docs-markdown/api

Anna agentillesi tämä URL-osoite tai yhdistä agentti suoraan MCP-palvelimeen.