Get Started

Environment Setup

This page is for anyone who hasn't called an HTTP API from a terminal before. If you're already comfortable with curl and environment variables, skip straight to Quickstart.

Install a client

You need something that can send an HTTP request with custom headers. Two common options:

  • curl — a command-line tool, usually already installed on macOS and Linux. Check with curl --version in a terminal. On Windows, install it via curl.se/windows or use curl bundled with Git Bash / WSL. Every example in these docs is written as a curl command first.
  • Postman (or Insomnia) — a graphical app for building and saving requests, useful if you'd rather click through a form than write shell commands. Install it from postman.com/downloads, then recreate any curl example on this site by copying the URL, method, headers, and body into a new request.

Using the Python examples

Every code sample on this site has a Python tab built on the popular requests library — not an official ImageToTable.ai SDK (we don't publish one; these are plain HTTP calls with any standard client). You need:

  • Python 3.8+ — check with python3 --version. Get it from python.org/downloads if it's missing.
  • requests — not part of the standard library, install it first:
    pip install requests
    (or pip3 install requests, depending on your system).

The export examples that parse the downloaded file (xlsx/docx) also use openpyxl / python-docx — only needed if you're following those specific examples, install with pip install openpyxl python-docx.

Using the JavaScript examples

The JavaScript tab uses the native fetch API — no library to install — but does assume a reasonably current runtime:

  • Node.js 20+ if running server-side — check with node --version. Examples use top-level await and the global crypto.randomUUID(), both of which need a recent Node; on Node 18 (now end-of-life) crypto isn't reliably a global outside CommonJS/REPL and these examples can fail with a confusing crypto is not defined error that has nothing to do with your API key. Get a current version from nodejs.org.
  • Or just paste the snippet into a browser's DevTools console — every modern browser supports the same APIs (fetch, FormData, crypto.randomUUID()) natively, no install needed at all.

Get your API key

Your API key is issued from your account's profile settings page. The v1 API is available to paid plans (Basic and above); calling it from a Free-plan key returns a plan_required error rather than a missing-auth error, since the key itself is valid — it just isn't allowed to use v1 yet.

Store your key as an environment variable

Don't paste your key directly into a command you might share, screenshot, or commit to version control. Export it into your shell session instead, then reference it as $API_KEY in every request — every example on this site assumes this variable exists:

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

This only lasts for your current terminal session. For something more permanent, add the same line to your shell's startup file (~/.bashrc, ~/.zshrc, or equivalent) — or, if you're writing a script, load it from a .env file / secrets manager rather than hardcoding it in source.

Send a test request

Confirm your key and setup work before moving on to real documents:

curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

A working key on a paid plan returns your account snapshot (plan, role, available credits). Anything else, see the troubleshooting checklist below.

Troubleshooting checklist

Every v1 error comes back as JSON with a type/code/message — see the full Error Handling guide for the complete list. The fastest first checks for a request that isn't working:

  • Getting missing_api_key? Check the header is exactly Authorization: Bearer <key> — the word Bearer, a single space, then the key. A missing space or a stray quote character in $API_KEY both produce this.
  • Getting invalid_api_key? The key doesn't match any account, or the account is disabled. Re-copy it from your profile page — keys are long and easy to truncate when copy-pasting.
  • Getting plan_required? Your key is valid, but your account is on the Free plan. Upgrade to Basic or above to use v1.
  • Getting a connection error, not a JSON response? Double-check the URL starts with https://imagetotable.ai/api/v1/ and that you're using -X POST (or the right verb) for endpoints that require it — a GET request to a POST-only endpoint won't reach the route at all.
  • Uploading a file and getting an unexpected error? Multipart file uploads need -F "file=@/path/to/file.jpg" (curl's form-upload flag), not -d or a raw JSON body — mixing these up is the most common upload mistake. The leading @ tells curl to read that path as a real file on your own machine — it isn't a URL, and the file has to already exist there before you run the command. If you don't have a local file handy, skip this entirely: pass a url field instead of file and the server fetches it for you — see Quickstart.
  • Getting rate_limit_exceeded? See Rate Limits — limits are per-account, not per-request-type-you-expect, so a burst of polling calls can trip the same limit as a burst of uploads.
📮 contact email: [email protected]