External API v1

The NetConverter External API v1 is a live, key-authenticated REST API for integrating NetConverter into your automation and tooling. It lets you retrieve completed translation jobs (including the original and translated configuration text) and manage the files in your NetConverter workspace — upload source configurations, list folders, and download results.

Base URL

All API requests are made to:

https://api.netconverter.ai/external/v1

Interactive OpenAPI documentation is available at https://api.netconverter.ai/external/v1/docs (machine-readable spec at /external/v1/openapi.json). A service health probe is available at https://api.netconverter.ai/health.

Authentication

The API uses per-organization API keys. Keys are issued per organization by the NetConverter team — contact contact@netconverter.ai or your account contact to request a key. Each key is scoped to your tenant and carries explicit permission scopes:

• read:jobs — list jobs and download source / translated configurations
• read:files — list and download workspace files and folders
• write:files — upload, update, delete, and restore workspace files; create folders

Pass your key as a standard Bearer token in the Authorization header. Keys are prefixed nck_live_ (production) or nck_test_:

Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX

Rate Limits

Every key has two independent limits, enforced per key:

• Per-minute burst limit — default 60 requests/minute (sliding window). Exceeding it returns 429 with a Retry-After: 60 header.
• Daily quota — default 10,000 requests/day. Exceeding it returns 429 with a Retry-After: 3600 header.

Higher limits are available per key — contact us with your expected volume.

Response Envelope

All JSON endpoints return a consistent, versioned envelope. Endpoints that return raw configuration or file text return text/plain instead (noted per endpoint). Every response echoes a request identifier; you can also supply your own via an X-Request-ID header for end-to-end correlation.

{
  "success": true,
  "data": { ... },
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "api_version": "v1"
}

Jobs Endpoints

Requires the read:jobs scope.

List Jobs

Endpoint: GET /external/v1/jobs

Lists your organization's translation jobs. By default only comparable jobs are returned — completed jobs that have both a source and a translated configuration (the ones you can diff). Pass ?comparable=false to list every job, including analysis-only jobs (validation, optimization, prescan) that store no translated output.

curl https://api.netconverter.ai/external/v1/jobs \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX"

Response Example:

{
  "success": true,
  "data": {
    "jobs": [
      {
        "job_id": "tra_d3878ce06560",
        "source_vendor": "cisco_asa",
        "target_vendor": "palo_alto_set",
        "status": "completed",
        "batch_id": null,
        "created_at": "2026-06-10T18:42:11.503210"
      }
    ]
  },
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "api_version": "v1"
}

Get Job Details

Endpoint: GET /external/v1/jobs/{job_id}

Returns metadata for a single job, including deterministic artifact identifiers for its source and translated configurations.

curl https://api.netconverter.ai/external/v1/jobs/tra_d3878ce06560 \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX"

Response Example:

{
  "success": true,
  "data": {
    "job_id": "tra_d3878ce06560",
    "source_vendor": "cisco_asa",
    "target_vendor": "palo_alto_set",
    "status": "completed",
    "source_config_id": "tra_d3878ce06560:source",
    "translated_config_id": "tra_d3878ce06560:palo_alto_set"
  },
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "api_version": "v1"
}

Download Source Configuration

Endpoint: GET /external/v1/jobs/{job_id}/source

Returns the original (pre-translation) configuration as text/plain.

curl https://api.netconverter.ai/external/v1/jobs/tra_d3878ce06560/source \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX" \
  -o source.cfg

Download Translated Configuration

Endpoint: GET /external/v1/jobs/{job_id}/translated

Returns the translated configuration as text/plain.

curl https://api.netconverter.ai/external/v1/jobs/tra_d3878ce06560/translated \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX" \
  -o translated.cfg

Files Endpoints

Read endpoints require the read:files scope; write endpoints require write:files. These operate on the same workspace you see under "My Files" in the portal.

List Files

Endpoint: GET /external/v1/files

Lists workspace files. Optionally filter by folder with ?folder=uploads.

curl "https://api.netconverter.ai/external/v1/files?folder=uploads" \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX"

Get File Metadata

Endpoint: GET /external/v1/files/{file_id}

Returns metadata for a single file (filename, path, size, MIME type, timestamps).

Get File Content

Endpoint: GET /external/v1/files/{file_id}/content

Returns the file's text content as text/plain.

Download File

Endpoint: GET /external/v1/files/{file_id}/download

Returns the raw file bytes with its stored MIME type and a Content-Disposition: attachment header.

List Folders

Endpoint: GET /external/v1/folders

Lists the folders in your workspace.

Upload File

Endpoint: POST /external/v1/files/upload (scope: write:files)

Multipart upload. Fields: file (required) and folder (optional, defaults to uploads).

curl -X POST https://api.netconverter.ai/external/v1/files/upload \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX" \
  -F "file=@asa-running-config.txt" \
  -F "folder=uploads"

Update File Content

Endpoint: PUT /external/v1/files/{file_id}/content (scope: write:files)

Replaces a file's text content. JSON body:

{
  "content": "new file content"
}

Delete / Restore File

Endpoints: DELETE /external/v1/files/{file_id} and POST /external/v1/files/{file_id}/restore (scope: write:files)

Deletes are soft — a deleted file can be restored.

Create Folder

Endpoint: POST /external/v1/folders (scope: write:files)

JSON body: folder_name (required), parent_path (optional).

curl -X POST https://api.netconverter.ai/external/v1/folders \
  -H "Authorization: Bearer nck_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"folder_name": "migration-wave-1"}'

Error Handling

Errors use the same versioned envelope with a structured error object and an appropriate HTTP status code:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "job not found"
  },
  "request_id": "req_1a2b3c4d5e6f7a8b",
  "api_version": "v1"
}

HTTP Status Codes

• 200 - Success
• 400 - bad_request (invalid input)
• 401 - unauthorized (missing or invalid API key)
• 403 - forbidden (insufficient scope, or organization not active)
• 404 - not_found (job/file does not exist — or belongs to another organization)
• 422 - unprocessable (request body failed validation)
• 429 - rate_limited (per-minute limit or daily quota exceeded; see Retry-After)
• 503 - Service unavailable (the external API can be temporarily disabled platform-wide)

Vendor Identifiers

The source_vendor and target_vendor fields on job objects use the following platform identifiers:

• Source platforms: cisco_asa, fortinet, palo_alto_set, palo_alto_xml, palo_alto_panorama, cisco_ios_xe, juniper_junos, aruba_cx, aruba_os
• Target platforms: palo_alto_set, palo_alto_xml, palo_alto_panorama, fortinet, cisco_fmc, strata_cloud_manager, cisco_ios_xe, juniper_junos, aruba_cx

Note: Cisco ASA and Aruba OS are source-only platforms (NetConverter migrates off them, never onto them), while Cisco FMC and Strata Cloud Manager are target-only (API-managed destinations). See Supported Vendors for the full coverage matrix.

Typical Integration Workflow

1. Upload source configurations to your workspace via POST /external/v1/files/upload
2. Run the conversion in the NetConverter portal (Quick Convert or Conversion Studio)
3. Poll GET /external/v1/jobs for the completed job
4. Download the translated output via GET /external/v1/jobs/{job_id}/translated
5. Feed the result into your deployment pipeline, diff tooling, or review process

Support

For API support, key requests, or rate-limit increases, please contact us or email contact@netconverter.ai. Our team is available to help with integration and answer any questions.