Typemark Documentation

Typemark API

Luo API-token ja työskentele projektiesi ja julkaisujesi kanssa skriptien ja CI:n kautta.

Uuendatud 19. nov 20264 min lugemist

Typemark API mahdollistaa skriptien ja CI:n lukea projektejasi ja niiden julkaisuja, esimerkiksi odottaa julkaisun valmistumista ennen kuin julkaisu lähtee. Se on saatavilla jokaisessa tilauksessa.

Dokumenttien lataamiseen, muokkaamiseen ja julkaisemiseen terminaalista tai CI:stä käytä Typemark CLI:tä. Se on rakennettu tämän API:n päälle ja hoitaa synkronoinnin sekä ristiriidat puolestasi.

Luo API-token

  1. Avaa tilisi

    Napsauta nimeäsi hallintapaneelin sivupalkin alareunassa ja valitse sitten Account.

  2. Nimeä token

    Kohdassa API tokens anna tokenille nimi, joka kertoo, missä sitä käytetään, esimerkiksi GitHub Actions.

  3. Valitse vanhenemisaika

    Valitse 30 päivää, 90 päivää, vuosi tai ei koskaan. Kun token vanhenee, sen kanssa lähetetyt pyynnöt lakkaavat toimimasta.

  4. Kopioi se

    Napsauta Create token ja kopioi token. Se alkaa tmk_:llä.

Token toimii sinun puolestasi. Se voi lukea jokaista projektia, jonka omistat tai jonka jäsen olet, roolisi mukaan kussakin. Pidä se poissa koodista ja kaikesta julkisesta.

Peruuta token

Napsauta Account-sivulla tokenin vieressä Revoke-painiketta. Kaikki sitä käyttävät lakkaavat toimimasta välittömästi. Luettelo näyttää, milloin kukin token käytettiin viimeksi, joten voit tunnistaa ne, joita mikään ei enää tarvitse.

Tee pyyntö

Lähetä token Authorization-otsakkeessa. Kaikki päätepisteet sijaitsevat osoitteen https://typemark.dev/api/v1 alla.

curl https://typemark.dev/api/v1/user \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
{
  "user": {
    "id": "6945f00a-3d8a-4609-8dd8-eb4c1aa3fbab",
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "plan": "pro",
    "trialing": false
  },
  "token": {
    "name": "GitHub Actions",
    "hint": "tmk_…Z4Fr",
    "created_at": "2026-11-16T10:12:00Z",
    "last_used_at": "2026-11-16T10:14:00Z",
    "expires_at": "2027-02-14T10:12:00Z"
  }
}

plan on free, pro tai business. business on Enterprise-tilaus: API säilyttää tilauksen aiemman nimen, jotta sitä tarkistavat skriptit toimivat edelleen.

Päätepisteet

MethodPathReturns
GET/userTokenin käyttäjä, hänen tilauksensa ja itse token
GET/projectsKaikki projektit, jotka omistat tai joiden jäsen olet
GET/projects/{slug}Yksi projekti sivumäärineen ja viimeisimpine julkaisuineen
POST/projectsLuo projektin. Käytetään komennossa typemark create.
GET/projects/{slug}/deploymentsViimeisimmät julkaisut, uusin ensin
GET/projects/{slug}/deployments/{id}Yksi julkaisu
GET/projects/{slug}/filesKaikki projektin tiedostot Git-blob-tunnuksineen ja commitit, joista ne ovat peräisin
GET/projects/{slug}/archiveProjektin tiedostot .tar.gz-muodossa. Anna sha tiettyä commitia varten.
POST/projects/{slug}/pushMuuttaa, lisää tai poistaa tiedostoja yhtenä committina ja julkaisee sen. Käytetään komennossa typemark push.
POST/migrate/mintlifyMuuntaa Mintlifyn docs.json- tai mint.json-tiedoston tiedostoksi typemark.json. Käytetään komennossa typemark migrate.
POST/migrate/gitbook, /migrate/readmeMuuntaa GitBook-tilan tai ReadMe-projektin Typemark-sivuiksi ja tiedostoksi typemark.json. Käytetään komennossa typemark migrate.
POST/openapi/pagesSivut, jotka Typemark luo OpenAPI-speksistä: lähetä source (sen polku tiedostossa typemark.json), content (sen teksti) ja group. Käytetään komennossa typemark dev. Mitään ei tallenneta.
DELETE/tokenPeruuttaa pyynnön lähettäneen tokenin

Projektit

curl https://typemark.dev/api/v1/projects/acme-docs \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
{
  "project": {
    "id": "c1111111-1111-1111-1111-111111111111",
    "name": "Acme Docs",
    "slug": "acme-docs",
    "role": "owner",
    "locked": false,
    "repo_mode": "connected",
    "github_repo": "acme/docs",
    "deploy_mode": "auto",
    "deploy_status": "live",
    "site_status": "live",
    "url": "https://docs.acme.com",
    "editor_url": "https://typemark.dev/projects/acme-docs/editor",
    "last_deployed_at": "2026-11-16T09:58:41Z",
    "last_deploy_commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
    "updated_at": "2026-11-16T09:58:41Z",
    "pages_count": 24,
    "has_unpublished_changes": false,
    "last_deployment": {
      "id": "8d0c2f4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
      "status": "success",
      "commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
      "commit_message": "docs: update quickstart.mdx",
      "commit_author": "Ada Lovelace",
      "pages_changed": 1,
      "build_duration_ms": 1840,
      "error_message": null,
      "created_at": "2026-11-16T09:58:39Z",
      "completed_at": "2026-11-16T09:58:41Z"
    }
  }
}

GET /projects palauttaa jokaisesta projektista samat kentät, paitsi pages_count, has_unpublished_changes ja last_deployment.

Luo projekti

curl https://typemark.dev/api/v1/projects \
  -H "Authorization: Bearer $TYPEMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Docs", "slug": "acme-docs" }'

Luo projektin, jonka omistat, samalla tavalla kuin New project hallintapaneelissa: typemark.json ja muutama aloitussivu, sivusto offline-tilassa, kunnes julkaiset sen. slug on valinnainen; ilman sitä se luodaan nimestä. Vastaus on 201 projektin kanssa samassa muodossa kuin GET /projects/{slug}.

StatusCodeMeaning
403project_limitTilauksesi ei salli yhtään projektia lisää. Virhe sisältää upgrade_url-kentän.
403unconfirmedVahvista ensin sähköpostiosoitteesi
422slug_takenToisella projektilla on jo tämä slug
422invalidNimi on tyhjä, tai slug ei ole pelkkiä pieniä kirjaimia, numeroita ja väliviivoja tai sitä ei voi käyttää. Virhe sisältää field-kentän.
rolestring

Roolisi projektissa: owner, editor tai viewer. Katso Team members.

lockedboolean

true, kun projekti on vain luettavissa, koska omistajan tilaus ei kata sitä. Katso Billing.

repo_modestring

managed, kun Typemark isännöi repositorion, connected, kun se synkronoituu GitHubin kanssa. github_repo on asetettu yhdistetyille projekteille.

deploy_modestring

auto tai manual. Katso Publishing.

deploy_statusstring

Viimeisin build: pending, building, live tai failed.

site_statusstring

live, kun lukijat voivat nähdä sivuston, offline, kun se on piilotettu.

urlstring

Osoite, josta lukijat löytävät sivuston: mukautettu domain, kun se on vahvistettu, muuten https://{slug}.typemark.dev.

has_unpublished_changesboolean

Manual-julkaisutilassa true, kun on muokkauksia, joita ei ole vielä julkaistu.

Julkaisut

Jokainen sivuston julkaisu on deployment. Anna limit valitaksesi, kuinka monta saat takaisin: oletuksena 20, enintään 100.

curl "https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1" \
  -H "Authorization: Bearer $TYPEMARK_TOKEN"
{
  "deployments": [
    {
      "id": "8d0c2f4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
      "status": "success",
      "commit_sha": "4f2c9e1a7b3d5f6e8c0a1b2d3e4f5a6b7c8d9e0f",
      "commit_message": "docs: update quickstart.mdx",
      "commit_author": "Ada Lovelace",
      "pages_changed": 1,
      "build_duration_ms": 1840,
      "error_message": null,
      "created_at": "2026-11-16T09:58:39Z",
      "completed_at": "2026-11-16T09:58:41Z"
    }
  ]
}
statusstring

pending, building, success tai failed. Kun se on failed, error_message kertoo syyn.

Esimerkki: odota julkaisua CI:ssä

Kun olet työntänyt dokumentaatiomuutokset GitHubiin, odota, kunnes Typemark on julkaissut ne:

#!/usr/bin/env bash
set -euo pipefail

API="https://typemark.dev/api/v1/projects/acme-docs/deployments?limit=1"

for attempt in $(seq 1 30); do
  latest=$(curl -fsS "$API" -H "Authorization: Bearer $TYPEMARK_TOKEN")
  status=$(echo "$latest" | jq -r '.deployments[0].status')
  sha=$(echo "$latest" | jq -r '.deployments[0].commit_sha')

  if [ "$sha" = "$GITHUB_SHA" ] && [ "$status" = "success" ]; then
    echo "Published $sha"
    exit 0
  fi
  if [ "$sha" = "$GITHUB_SHA" ] && [ "$status" = "failed" ]; then
    echo "$latest" | jq -r '.deployments[0].error_message'
    exit 1
  fi
  sleep 5
done

echo "Timed out waiting for Typemark to publish $GITHUB_SHA"
exit 1

Virheet

Virheet palautetaan JSON-muodossa koodilla, jonka voit tarkistaa, ja viestillä, jonka voit näyttää:

{
  "error": {
    "code": "not_found",
    "message": "Not found."
  }
}
StatusCodeMeaning
400bad_requestPakollinen parametri puuttuu
401unauthorizedToken puuttuu, on väärä, peruutettu tai vanhentunut
403forbiddenRoolisi projektissa ei salli tätä, esimerkiksi viewer, joka yrittää työntää
403plan_limitProjektin omistajan tilaus ei sisällä tätä. Virhe sisältää feature- ja upgrade_url-kentät.
403project_limitProjektin luominen: tilauksesi ei salli yhtään lisää. Virhe sisältää upgrade_url-kentän.
403unconfirmedProjektin luominen: vahvista ensin sähköpostiosoitteesi
404not_foundProjektia tai julkaisua ei ole, tai et ole projektin jäsen
409conflictPush muuttaa tiedostoja, jotka ovat muuttuneet myös Typemarkissa base_sha:n jälkeen. Virhe luettelee ne kentässä conflicts.
409stale_basePush perustuu committiin, jota Typemarkilla ei ole. Vedä projekti uudelleen ja työnnä sitten.
409connected_repoProjekti synkronoituu GitHubin kanssa, joten pushit menevät sen sijaan GitHubiin
409busyProjektiin tehdään parhaillaan toista muutosta. Yritä hetken päästä uudelleen.
413too_largePush ylittää rajat: 500 tiedostoa, 10 MB per tiedosto, 50 MB per push, 100 MB per projekti. OpenAPI-speksi yli 10 MB.
422slug_taken, invalidProjektin luominen: slug on varattu, tai nimi tai slug ei ole kelvollinen (field kertoo, mikä)
422invalid_specOpenAPI-speksi, jota ei voi jäsentää. Viesti kertoo missä.
422invalid_pathPush nimeää polun, jonka Typemark ei kirjoita: tyhjä, alkaa /:llä, sisältää kenoviivan, . tai .., tai on kansiossa .git/ tai .typemark/
422not_mintlify, not_gitbook, not_readmeMigrointi: tiedostot eivät näytä Mintlify-konfiguraatiolta, GitBook-tilalta tai ReadMe-projektilta
426cli_outdatedTypemark CLI on liian vanha API:lle. hint kertoo, miten päivittää. Vain pyynnöt, jotka ilmoittavat CLI-version, saavat tämän.
429Liian monta pyyntöä. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja.
503git_errorProjektin repositorioa ei voitu lukea tai kirjoittaa. Yritä hetken päästä uudelleen.

Rajat

Jokainen IP-osoite voi tehdä 300 API-pyyntöä minuutissa, mukaan lukien enintään 30 pushia, 30 arkiston latausta ja 30 OpenAPI-speksiä.