KittyCAD logo

KittyCAD

API Reference

KittyCAD's API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The root endpoint / returns the OpenAPI specification for the API. It's handy if you want to use it to generate things.

Base url
https://api.kittycad.io
Client libraries

Authentication

KittyCAD's API uses API keys, also referred to as API tokens, to authenticate requests. You can view and manage your API keys in your account on the KittyCAD website.

Authentication to the API is performed via Bearer Token Auth. Provide your API key as the token value. We will automatically add your token to the examples here if you are logged in.

All API requests must be made over HTTPS. API requests without authentication will fail.

Authenticated request
$ curl --header "Authorization: Bearer $TOKEN" \
	"https://api.kittycad.io/_meta/debug/session"

Errors

KittyCAD uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with KittyCAD's servers (these are rare).

HTTP Status Code Summary
400 - Bad RequestThe request failed could not authenticate, but the token existed.
401 - UnauthorizedNo valid API key provided.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
406 - Not AcceptableThe request was unacceptable, often due to missing a required parameter.
500 - Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.

File

CAD file operations.

Endpoints
POST /file/conversion/{sourceFormat}/{outputFormat}
GET /file/conversion/{id}

Convert CAD file   
beta

Convert a CAD file from one format to another. If the file being converted is larger than a certain size it will be performed asynchronously.

Parameters

  • sourceFormatstringrequired

    The format of the file to convert.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • outputFormatstringrequired

    The format the file should be converted to.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae

Returns

200 OK

Returns the contents of the converted file, base64 encoded, if successful.

  • idstring

    The id of the file conversion.

  • created_atstring

    The date and time the file conversion was created.

  • completed_atstring

    The date and time the file conversion was completed.

  • statusstring

    The status of the file conversion.

    Possible values
    • Queued
    • Uploaded
    • In Progress
    • Completed
    • Failed
  • src_formatstring

    The format of the original file uploaded to be converted.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • output_formatstring

    The output format requested for the file.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • outputstring

    The converted file, base64 encoded.

202 Accepted

The file conversion is being performed asynchronously. You can use the `id` returned from the request to poll for status information about the conversion.

  • idstring

    The id of the file conversion.

  • created_atstring

    The date and time the file conversion was created.

  • completed_atstring

    The date and time the file conversion was completed.

  • statusstring

    The status of the file conversion.

    Possible values
    • Queued
    • Uploaded
    • In Progress
    • Completed
    • Failed
  • src_formatstring

    The format of the original file uploaded to be converted.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • output_formatstring

    The output format requested for the file.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • outputstring

    The converted file, base64 encoded.

post/file/conversion/{sourceFormat}/{outputFormat}
$ curl -X POST "https://api.kittycad.io/file/conversion/{sourceFormat}/{outputFormat}" \
	--header "Authorization: Bearer $TOKEN" \
	--data "@/path/to/a/base64_encoded_file"
200 Response
{
  "id": "6970d4f2-8979-4461-a9a1-ace62548fb5f",
  "created_at": "2021-11-02T21:48:05+0000",
  "completed_at": "2021-11-02T23:12:05+0000",
  "user_id": "ckv5prd3j000607mlnmwlpyz8",
  "src_format": "obj",
  "output_format": "step",
  "output": "BASE64_ENCODED_FILE_OUTPUT",
  "status": "Completed"
}
202 Response
{
  "id": "6970d4f2-8979-4461-a9a1-ace62548fb5f",
  "created_at": "2021-11-02T21:48:05+0000",
  "user_id": "ckv5prd3j000607mlnmwlpyz8",
  "src_format": "obj",
  "output_format": "step",
  "status": "Uploaded"
}

Get a file conversion   
beta

Get the status of a file conversion.

Parameters

  • idstringrequired

    The id of the file conversion.

Returns

200 OK

Returns the status of the file conversion. If completed, the contents of the converted file will be returned as a base64 encoded string.

  • idstring

    The id of the file conversion.

  • created_atstring

    The date and time the file conversion was created.

  • completed_atstring

    The date and time the file conversion was completed.

  • statusstring

    The status of the file conversion.

    Possible values
    • Queued
    • Uploaded
    • In Progress
    • Completed
    • Failed
  • src_formatstring

    The format of the original file uploaded to be converted.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • output_formatstring

    The output format requested for the file.

    Possible values
    • step
    • obj
    • stl
    • dxf
    • fbx
    • dae
  • outputstring

    The converted file, base64 encoded.

get/file/conversion/{id}
$ curl "https://api.kittycad.io/file/conversion/{id}" \
	--header "Authorization: Bearer $TOKEN"
200 Response
{
  "id": "6970d4f2-8979-4461-a9a1-ace62548fb5f",
  "created_at": "2021-11-02T21:48:05+0000",
  "user_id": "ckv5prd3j000607mlnmwlpyz8",
  "src_format": "obj",
  "output_format": "step",
  "status": "In Progress"
}

Meta

Meta information about servers, instances, and sessions.

Endpoints
GET /_meta/debug/session
GET /_meta/debug/instance
GET /ping

Get auth session

Get information about your API request session. This is primarily used for debugging.

Parameters

No parameters

Returns

200 OK

Returns the authorized user's authentication session if successful.

  • idstring

    The id of the session.

  • tokenstring

    The user's token.

  • user_idstring

    The user's id.

  • emailstring

    The user's email address.

  • ip_addressstring

    The IP address the request originated from.

  • is_validboolean

    If the token is valid.

  • created_atstring

    The date and time the session/request was created.

get/_meta/debug/session
$ curl "https://api.kittycad.io/_meta/debug/session" \
	--header "Authorization: Bearer $TOKEN"
200 Response
{
  "created_at": "2021-11-02T21:48:05+0000",
  "id": "6970d4f2-8979-4461-a9a1-ace62548fb5f",
  "ip_address": "203.0.113.0",
  "is_valid": true,
  "token": "435f9688-365f-4a2d-860b-554798160cfe",
  "user_id": "ckv5prd3j000607mlnmwlpyz8"
}

Get instance metadata

Get information about this specific API server instance. This is primarily used for debugging.

Parameters

No parameters

Returns

200 OK

Returns the instance metadata if successful.

  • idstring

    The id of the instance.

  • git_hashstring

    The git hash of the code the server was built from.

  • environmentstring

    The type of environment.

    Possible values
    • DEVELOPMENT
    • PREVIEW
    • PRODUCTION
  • namestring

    The name of the instance.

  • descriptionstring

    The description of the instance.

  • ip_addressstring

    The IP address of the instance.

  • zonestring

    The zone of the instance.

  • imagestring

    The image that was used as the base of the instance.

  • hostnamestring

    The hostname of the instance.

  • cpu_platformstring

    The CPU platform of the instance.

  • machine_typestring

    The machine type of the instance.

get/_meta/debug/instance
$ curl "https://api.kittycad.io/_meta/debug/instance" \
	--header "Authorization: Bearer $TOKEN"
200 Response
{
  "id": "3247495290486004999",
  "cpu_platform": "Intel Haswell",
  "environment": "PRODUCTION",
  "git_hash": "d454900",
  "hostname": "api-us-central1-0kph.us-central1-f.c.kittycadapi.internal",
  "image": "projects/kittycadapi/global/images/packer-1635462081",
  "ip_address": "10.127.15.206",
  "machine_type": "projects/199385932268/machineTypes/n1-standard-16",
  "name": "api-us-central1-0kph",
  "zone": "projects/199385932268/zones/us-central1-f",
  "description": "An API server instance."
}

Ping

Simple ping to the server.

Parameters

No parameters

Returns

200 OK

Returns the message "pong" if successful.

  • messagestring

    The message.

get/ping
$ curl "https://api.kittycad.io/ping"
200 Response
{
  "message": "pong"
}