Quickstart / TypeScript

Integrate with typed, failure-aware server code.

This dependency-free example works today. The generated workspace client is documented separately and follows the same OpenAPI contract.

TypeScript SDK reference

Create one bounded job

Run this only on the server. Browser bundles must not contain API keys.

server.tsts

const api = 'https://api.getmd.xyz';
const token = process.env.GETMD_API_KEY;
if (!token) throw new Error('GETMD_API_KEY is required');

const response = await fetch(api + '/v1/jobs', {
  method: 'POST',
  headers: {
    authorization: 'Bearer ' + token,
    'content-type': 'application/json',
    'idempotency-key': crypto.randomUUID()
  },
  body: JSON.stringify({
  "source": {
    "type": "text",
    "content": "The Acorn API v2 adds cursor pagination. Existing v1 endpoints remain supported through 2027.",
    "title": "Original release note"
  },
  "output": {
    "profile": "agent_context",
    "format": "markdown",
    "language": "en",
    "include_raw_source": false
  },
  "retention": {
    "class": "temporary"
  }
})
});
if (!response.ok) throw new Error(await response.text());
const job = await response.json();

Poll with a ceiling

Honor Retry-After, apply jitter in shared systems, and enforce a caller-owned deadline. A network timeout does not mean the durable job failed.

Polling rulets

for (let attempt = 0; attempt < 60; attempt += 1) {
  const current = await fetch(api + '/v1/jobs/' + job.id, {
    headers: { authorization: 'Bearer ' + token }
  }).then(async (value) => value.ok ? value.json() : Promise.reject(new Error(await value.text())));
  if (['succeeded', 'failed', 'canceled', 'expired'].includes(current.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 2_000));
}

Validate the outcome

The example uses original text, temporary retention, one output, and bounded reads. Inspect warnings and expiry before handing the result to another system.

Check status and warnings.
Read outputs using returned IDs.
Do not log the bearer token or raw private source.