> ## Documentation Index
> Fetch the complete documentation index at: https://help.draftable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with the Draftable API

> An introduction to the Draftable API: what it does, how a comparison flows through it, and a complete first request from credentials to viewable result.

The Draftable API lets you compare two documents programmatically and present the result to your users, without building any comparison logic yourself.

This article is the starting point. Work through it and you will have created your first comparison and viewed the result. The articles that follow go deeper into each step.

## What the API does

You send Draftable two documents. Draftable compares them and produces an interactive **Side-by-Side comparison** that your users open in a browser, showing exactly what changed between the two versions.

Supported file types are **PDF, Word (.doc, .docx, .docm), PowerPoint (.ppt, .pptx, .pptm), RTF and plain text**. You can compare across formats, so a Word document can be compared against a PDF.

## How a comparison flows

Every integration follows the same four stages. Understanding this shape makes the rest of the API straightforward.

<Steps>
  <Step title="Create the comparison">
    You send both documents to Draftable, either as direct uploads or as URLs Draftable fetches for you. Draftable responds immediately with a **comparison identifier**.
  </Step>

  <Step title="Draftable processes it">
    Comparison happens asynchronously. Larger documents take longer.
  </Step>

  <Step title="You wait for it to be ready">
    You either poll the comparison until it reports as ready, or hand the user a viewer URL that waits for you.
  </Step>

  <Step title="You present the result">
    You give the user a **viewer URL**. Optionally, you also export the comparison to PDF.
  </Step>
</Steps>

<Note>
  Creating a comparison is fast and always returns straight away. It does not block while the documents are compared. Any integration you build needs to account for the comparison not being ready the instant you create it.
</Note>

## Before you start

You need an **account ID** and an **auth token**. Both are available from your account at [api.draftable.com/account/credentials](https://api.draftable.com/account/credentials).

You will see two sets: one labelled test and one labelled production. Use the **test** credentials while you are building. They behave identically to production credentials but keep your development traffic separate. See [Test and production accounts](/hc/en-us/articles/Draftable-API-test-and-production-accounts) for the detail.

## Your first comparison

The API is available at:

```
https://api.draftable.com/v1
```

Authenticate by sending your auth token in an `Authorization` header.

### Step 1: Create a comparison

The simplest way to start is with two documents Draftable can fetch by URL. Draftable hosts sample documents you can use for this.

```bash theme={null}
curl -X POST https://api.draftable.com/v1/comparisons \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -F "left.source_url=https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf" \
  -F "left.file_type=rtf" \
  -F "right.source_url=https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf" \
  -F "right.file_type=pdf"
```

Draftable responds with the new comparison:

```json theme={null}
{
  "identifier": "aBcDeFgH",
  "left":  { "source_url": "...", "file_type": "rtf" },
  "right": { "source_url": "...", "file_type": "pdf" },
  "creation_time": "2026-09-02T09:15:00.000Z",
  "public": false,
  "ready": false
}
```

Note `"ready": false`. The comparison exists, but Draftable is still working on it. Keep the `identifier`, as everything else you do refers to it.

### Step 2: Check whether it is ready

```bash theme={null}
curl https://api.draftable.com/v1/comparisons/aBcDeFgH \
  -H "Authorization: Token YOUR_AUTH_TOKEN"
```

When processing finishes, `ready` becomes `true` and a `ready_time` appears. Check `failed` as well, because a comparison can finish unsuccessfully.

### Step 3: View the result

Open the comparison in the viewer:

```
https://api.draftable.com/v1/viewer/YOUR_ACCOUNT_ID/aBcDeFgH
```

By default comparisons are private, so this URL requires a signature. [Viewing and sharing comparison results](/hc/en-us/articles/Draftable-API-viewing-and-sharing-results) explains how to generate one, and how to avoid polling entirely using the `wait` parameter.

## Use a client library

Everything above is a plain REST call, so any HTTP client works. For most integrations the official client libraries are quicker, because they handle authentication, polling and viewer URL signing for you.

Libraries are available for **.NET, Node.js, Python and Java**. See [API client libraries](/hc/en-us/articles/7132291518233-API-client-libraries).

Here is the same comparison in Python:

```python theme={null}
import draftable

client = draftable.Client(ACCOUNT_ID, AUTH_TOKEN)
comparisons = client.comparisons

comparison = comparisons.create(
    left=draftable.make_side("https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf", file_type="rtf"),
    right=draftable.make_side("https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf", file_type="pdf"),
)

print(comparisons.signed_viewer_url(comparison.identifier))
```

## Where to go next

<CardGroup>
  <Card title="Authenticating with the Draftable API" icon="key" href="/hc/en-us/articles/Draftable-API-authentication" iconType="solid" horizontal />

  <Card title="Test and production accounts" icon="flask" href="/hc/en-us/articles/Draftable-API-test-and-production-accounts" iconType="solid" horizontal />

  <Card title="Creating a comparison" icon="file-import" href="/hc/en-us/articles/Draftable-API-creating-a-comparison" iconType="solid" horizontal />

  <Card title="Viewing and sharing results" icon="eye" href="/hc/en-us/articles/Draftable-API-viewing-and-sharing-results" iconType="solid" horizontal />

  <Card title="Exporting a comparison to PDF" icon="file-pdf" href="/hc/en-us/articles/Draftable-API-exporting-comparisons" iconType="solid" horizontal />

  <Card title="Handling errors and failures" icon="triangle-exclamation" href="/hc/en-us/articles/Draftable-API-handling-errors" iconType="solid" horizontal />
</CardGroup>