API overview

The IntoSQL API converts files on IntoSQL's servers with the same engine as the converter on the site. You send a file, or the address of one, start the conversion, and download the SQL when it's done. A MySQL or MariaDB dump (.sql or .sql.gz) converts the same way into a PostgreSQL script (MySQL to PostgreSQL). A webhook can tell you when that happens.

Pro: The API is part of IntoSQL Pro. Each month includes 5 GB of files converted on IntoSQL's servers.

Base address#

Every endpoint lives under one address, and every request and answer is JSON.

https://intosql.com/api/v1

The OpenAPI 3.1 document at /api/v1/openapi.json describes every endpoint, field and error. Point an API client or a code generator at it.

Authentication#

Make a key in Settings, API keys and send it as a bearer token. A key belongs to your account: anyone who has it can convert files on your plan, so keep it on the server and out of browsers and repositories.

curl https://intosql.com/api/v1/usage \
  -H "Authorization: Bearer $INTOSQL_API_KEY"

A request without a key, or with one that was deleted, gets 401 with the code unauthenticated. An account without Pro gets 402 with needs_pro.

How a conversion goes#

1. Open a conversion. POST /conversions with the file's name, its size in bytes and the conversion spec. The answer has an upload address, valid for an hour.
2. Upload the file. PUT the file's bytes to upload.url with the headers in upload.headers, exactly as given.
3. Start it. POST /conversions/{id}/start. The conversion is queued, then running, then done or failed. POST /conversions/{id}/cancel stops it on the way.
4. Read the result. GET /conversions/{id} until status is done; output.url then downloads the SQL for ten minutes. Read the conversion again for a fresh address.

To skip the upload, send url instead of name and bytes: a public HTTPS address of the file. IntoSQL downloads it and starts right away, and the answer is 202.

curl -X POST https://intosql.com/api/v1/conversions \
  -H "Authorization: Bearer $INTOSQL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/exports/ventas.csv", "spec": {"output": {"dialect": "postgresql"}}}'

Each SDK, in TypeScript, PHP, Python, Java, Go, .NET or Ruby, does all four steps in one call.

Files and how long they stay#

• An upload takes files up to 5 GiB, the most one PUT to storage holds. A file sent by url can be up to 50 GiB.
• The uploaded file and the output are deleted 24 hours after the conversion ends. DELETE /conversions/{id} deletes them right away.
• A failed conversion keeps its upload for those 24 hours, so you can send it to us if it didn't convert well.
• Each conversion's expires_at says when its files go.

Limits#

GET /usage tells you how much of this month's allowance is left.

Retrying safely#

Opening and starting a conversion accept an Idempotency-Key header. Send a unique value, such as a UUID, and use the same one when you retry after a timeout or a lost connection: the retry gets the first request's answer instead of opening a second conversion. Reusing a key for a different request gets 422 with idempotency_mismatch; retrying while the first request still runs gets 409 with request_in_progress.

Errors#

Every error has the same shape: a code that never changes, for your code to read, and a message for people.

{
    "error": {
        "code": "invalid_request",
        "message": "Some fields are missing or invalid.",
        "fields": {
            "spec": ["The spec field is required."]
        },
        "request_id": "req_01k7r3jb2c4e6g8j0m2p4r6t8v"
    }
}

Errors lists every code with its status and what to do.

Webhooks#

Instead of reading a conversion until it ends, save a webhook address in Settings, API keys. IntoSQL calls it when a conversion is done, failed or canceled, signed so you can check it came from IntoSQL. See Webhooks.

Versions#

The API is versioned in its path: /api/v1. Within v1, changes only add: new fields in answers, new error codes, new endpoints, new optional fields in requests. Write your code to ignore fields it doesn't know and to treat an unknown error code like its HTTP status.

Nothing in v1 is renamed or removed without notice. Before an endpoint or field goes, its answers carry a Deprecation header and a Sunset header with the date it stops working, at least six months ahead, and the change is listed here. A change that can't be made by adding gets a new version, /api/v2, with v1 kept alongside.

Every answer carries an X-Request-Id. Quote it when you write to us about a request.