Revit automation API. Parameters, jobs and outputs.

modelKit works with prepared RFA families. Before your first request, you need an organization and project, a published template, an integration key and a Revit client linked to the project.

1. 1. Prepare. Upload an RFA to the dashboard. Run an inspection, configure the fields, validate the revision in Revit and publish it.
2. 2. Get the contract. Retrieve the available catalog and the JSON Schema for your selected template.
3. 3. Preview. Check mappings and default values without creating a job.
4. 4. Create a job. Submit the configuration with a request_id. Revit processes it when a compatible client is available.
5. 5. Get the outputs. Read the status, review any errors and download the available files.

This workflow saves a standalone family. It does not place an instance in an open RVT project or convert drawings or images into BIM models.

Integration requests require a Bearer token for a client belonging to one project. An administrator assigns scopes and model access. The key can access only its own jobs and permitted templates.

Authorization: Bearer <integration_token>
Content-Type: application/json

Issue or rotate keys through Django admin or the register_modelkit_client server command. Store the key on the server side of your integration. The Revit client uses a separate key, which is not valid for the producer API.

For the session API, GET /api/cabinet/csrf/ returns CSRF data, POST /api/cabinet/auth/login/ signs in and GET /api/cabinet/me/ returns the user. These routes are separate from the Bearer API below.

All endpoint paths below are relative to /api/modelkit/v1/. Keep the trailing slash. The catalog is limited by the project and the permissions assigned to your key.

# BASE_URL is your deployment root; TOKEN is your integration key
curl "$BASE_URL/api/modelkit/v1/catalog/" \
  -H "Authorization: Bearer $TOKEN"

The catalog returns templates with product_type_id, fields, revit_version, revision and contract_url. The contract contains json_schema, example, revision details, dependencies and validation results. Use the example from your template contract for the first request.

Configuration changes are saved in a draft. Publication follows validation scenarios and approval; the integration contract does not expose the draft pending_revision. Revision comparisons are available for published and superseded revisions.

Preview maps and validates fields without creating a job or recalculating geometry. The example below uses illustrative dimension keys. Replace product_type_id with an ID from your catalog and use the parameter names and values defined by its contract.

{
  "product_type_id": "<product_type_id>",
  "parameters": {
    "Width": 3000,
    "Height": 3000,
    "Depth": 400
  }
}

The response contains template_id, revit_version, cleaned parameters and mapping. Review mapped, unmapped_parameters, defaults and warnings inside mapping. Unmapped fields do not control geometry.

After reviewing preview, submit the configuration with a nonempty request_id of up to 128 characters. The example explicitly accepts warnings; use this flag only after reviewing mapping.

{
  "request_id": "order-123-item-1-rev-1",
  "product_type_id": "<product_type_id>",
  "parameters": {
    "Width": 3000,
    "Height": 3000,
    "Depth": 400
  },
  "accept_mapping_warnings": true,
  "outputs": [
    "rfa",
    "mesh.json",
    "front.dwg",
    "top.dwg",
    "side.dwg",
    "combined.dwg"
  ]
}

Save the JSON as job.json. Replace the template ID and use a new request_id for each new configuration.

curl -X POST "$BASE_URL/api/modelkit/v1/jobs/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @job.json

The response includes error, error_code, error_detail, timings, mapping, requested_outputs and artifacts. The result may contain audit, preview_error and dwg_errors. The artifacts list includes only available files, their URLs and download metadata.

When outputs is omitted, all six files are requested. An explicit list must be nonempty and contain no duplicates. PDF, XLSX, IFC and RVT are not supported outputs. The ZIP package is available for succeeded or partial jobs and includes available files, request.json, result.json, parameter-receipt.json, manifest.json and manifest.sig.

curl "$BASE_URL/api/modelkit/v1/jobs/$JOB_ID/" \
  -H "Authorization: Bearer $TOKEN"

# Download the package after succeeded or partial
curl --fail "$BASE_URL/api/modelkit/v1/jobs/$JOB_ID/package/" \
  -H "Authorization: Bearer $TOKEN" \
  --output result.zip

Job listing, retries and cancellation are handled by the dashboard and separate session routes. This integration API does not provide GET /jobs/ or POST /jobs/{job_id}/cancel/.

Pass callback_url when creating a job. There is no separate subscription endpoint. By default, it must be an HTTPS URL without credentials or a fragment; localhost and private addresses are rejected. The receiver gets started and attention events, plus the terminal states succeeded, partial, failed and cancelled.

Content-Type: application/json
X-ModelKit-Event: succeeded
X-ModelKit-Delivery: <delivery_id>
X-ModelKit-Timestamp: <unix_timestamp>
X-ModelKit-Signature: sha256=<hex_digest>

The JSON contains event, event_id, job_id, request_id, status, stage, error_code, occurred_at and status_url. For succeeded and partial, package_url is added. The event_id is formed as job_id:event; use it to prevent duplicate processing.

message = UTF8(timestamp + ".") + raw_request_body
signature = HMAC_SHA256(signing_secret, message).hexdigest()
header = "sha256=" + signature

HTTP 2xx marks successful delivery. Defaults are 8 attempts and a 10-second request timeout. After an error, the delay is min(3600, 2^attempts × 5) seconds. The operator can configure these values; actual delivery depends on running the delivery command. When callbacks are enabled, the job response webhook field shows delivered, pending and failed counts.

General errors return an error string. Parameter validation errors return an errors object whose keys identify invalid fields or mappings. The message below is translated for reference; actual response wording may differ.

{
  "errors": {
    "request_id": "A nonempty string of up to 128 characters. Reuse it when retrying after network errors."
  }
}

parameters accepts up to 512 fields; product.inputParameters accepts up to 512 entries. Input parameter names must be 1–120 characters. Values must be scalar, with a string representation of up to 4096 characters. REVIT_MAX_QUEUED_JOBS sets the queue limit, which defaults to 1,000 queued jobs per project. This handler does not impose a universal requests-per-minute limit.