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
Avaa tilisi
Napsauta nimeäsi hallintapaneelin sivupalkin alareunassa ja valitse sitten Account.
Nimeä token
Kohdassa API tokens anna tokenille nimi, joka kertoo, missä sitä käytetään, esimerkiksi
GitHub Actions.Valitse vanhenemisaika
Valitse 30 päivää, 90 päivää, vuosi tai ei koskaan. Kun token vanhenee, sen kanssa lähetetyt pyynnöt lakkaavat toimimasta.
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
| Method | Path | Returns |
|---|---|---|
GET | /user | Tokenin käyttäjä, hänen tilauksensa ja itse token |
GET | /projects | Kaikki projektit, jotka omistat tai joiden jäsen olet |
GET | /projects/{slug} | Yksi projekti sivumäärineen ja viimeisimpine julkaisuineen |
POST | /projects | Luo projektin. Käytetään komennossa typemark create. |
GET | /projects/{slug}/deployments | Viimeisimmät julkaisut, uusin ensin |
GET | /projects/{slug}/deployments/{id} | Yksi julkaisu |
GET | /projects/{slug}/files | Kaikki projektin tiedostot Git-blob-tunnuksineen ja commitit, joista ne ovat peräisin |
GET | /projects/{slug}/archive | Projektin tiedostot .tar.gz-muodossa. Anna sha tiettyä commitia varten. |
POST | /projects/{slug}/push | Muuttaa, lisää tai poistaa tiedostoja yhtenä committina ja julkaisee sen. Käytetään komennossa typemark push. |
POST | /migrate/mintlify | Muuntaa Mintlifyn docs.json- tai mint.json-tiedoston tiedostoksi typemark.json. Käytetään komennossa typemark migrate. |
POST | /migrate/gitbook, /migrate/readme | Muuntaa GitBook-tilan tai ReadMe-projektin Typemark-sivuiksi ja tiedostoksi typemark.json. Käytetään komennossa typemark migrate. |
POST | /openapi/pages | Sivut, 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 | /token | Peruuttaa 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}.
| Status | Code | Meaning |
|---|---|---|
403 | project_limit | Tilauksesi ei salli yhtään projektia lisää. Virhe sisältää upgrade_url-kentän. |
403 | unconfirmed | Vahvista ensin sähköpostiosoitteesi |
422 | slug_taken | Toisella projektilla on jo tämä slug |
422 | invalid | Nimi 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. |
rolestringRoolisi projektissa: owner, editor tai viewer. Katso Team members.
lockedbooleantrue, kun projekti on vain luettavissa, koska omistajan tilaus ei kata sitä. Katso Billing.
repo_modestringmanaged, kun Typemark isännöi repositorion, connected, kun se synkronoituu GitHubin kanssa. github_repo on asetettu yhdistetyille projekteille.
deploy_modestringauto tai manual. Katso Publishing.
deploy_statusstringViimeisin build: pending, building, live tai failed.
site_statusstringlive, kun lukijat voivat nähdä sivuston, offline, kun se on piilotettu.
urlstringOsoite, josta lukijat löytävät sivuston: mukautettu domain, kun se on vahvistettu, muuten https://{slug}.typemark.dev.
has_unpublished_changesbooleanManual-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"
}
]
}
statusstringpending, 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."
}
}
| Status | Code | Meaning |
|---|---|---|
400 | bad_request | Pakollinen parametri puuttuu |
401 | unauthorized | Token puuttuu, on väärä, peruutettu tai vanhentunut |
403 | forbidden | Roolisi projektissa ei salli tätä, esimerkiksi viewer, joka yrittää työntää |
403 | plan_limit | Projektin omistajan tilaus ei sisällä tätä. Virhe sisältää feature- ja upgrade_url-kentät. |
403 | project_limit | Projektin luominen: tilauksesi ei salli yhtään lisää. Virhe sisältää upgrade_url-kentän. |
403 | unconfirmed | Projektin luominen: vahvista ensin sähköpostiosoitteesi |
404 | not_found | Projektia tai julkaisua ei ole, tai et ole projektin jäsen |
409 | conflict | Push muuttaa tiedostoja, jotka ovat muuttuneet myös Typemarkissa base_sha:n jälkeen. Virhe luettelee ne kentässä conflicts. |
409 | stale_base | Push perustuu committiin, jota Typemarkilla ei ole. Vedä projekti uudelleen ja työnnä sitten. |
409 | connected_repo | Projekti synkronoituu GitHubin kanssa, joten pushit menevät sen sijaan GitHubiin |
409 | busy | Projektiin tehdään parhaillaan toista muutosta. Yritä hetken päästä uudelleen. |
413 | too_large | Push ylittää rajat: 500 tiedostoa, 10 MB per tiedosto, 50 MB per push, 100 MB per projekti. OpenAPI-speksi yli 10 MB. |
422 | slug_taken, invalid | Projektin luominen: slug on varattu, tai nimi tai slug ei ole kelvollinen (field kertoo, mikä) |
422 | invalid_spec | OpenAPI-speksi, jota ei voi jäsentää. Viesti kertoo missä. |
422 | invalid_path | Push nimeää polun, jonka Typemark ei kirjoita: tyhjä, alkaa /:llä, sisältää kenoviivan, . tai .., tai on kansiossa .git/ tai .typemark/ |
422 | not_mintlify, not_gitbook, not_readme | Migrointi: tiedostot eivät näytä Mintlify-konfiguraatiolta, GitBook-tilalta tai ReadMe-projektilta |
426 | cli_outdated | Typemark CLI on liian vanha API:lle. hint kertoo, miten päivittää. Vain pyynnöt, jotka ilmoittavat CLI-version, saavat tämän. |
429 | Liian monta pyyntöä. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja. | |
503 | git_error | Projektin 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ä.