Put published models into your applications
The AscentML API gives technical teams direct access to published models, batch jobs, and prediction explanations.
This page summarizes how the API works. Customers have access to the full OpenAPI specification and interactive Swagger documentation inside the platform.
-
1
Conventions
The API is a versioned JSON REST API. All endpoints are served under
/api/v1.- Consistent resource naming
- Pagination, filtering, and sorting on list endpoints
- Structured validation errors with stable error codes
- A correlation ID on every request
- Idempotency keys for operations that should not run twice
-
2
Authentication
Requests are authenticated with an API key. Keys are created by users in the platform and belong to the user who created them.
- A key can never exceed the permissions of its owner
- Keys can be limited to specific projects or models
- The full secret is shown once, at creation or rotation
- Keys are identified by a visible prefix, such as
aml_live_xxxxxxxx - Keys can be rotated or revoked at any time
AscentML stores only a hash of each key. If a secret is lost, rotate the key.
-
3
Real-time inference
Choose the endpoint that matches how you want to select a model.
Through a deployment
POST /api/v1/deployments/{deploymentId}/inferenceRecommended for production. Requests follow the deployment’s current traffic allocation. Supplying a routing key keeps a given caller on the same model version for as long as the allocation is unchanged.
Through a project
POST /api/v1/projects/{projectId}/inferenceAgainst a specific model version
POST /api/v1/models/{modelId}/versions/{versionId}/inferenceUseful for testing and comparison when you need a fixed version.
Responses can include the prediction, confidence, model version, timestamp, and request information. Rows that cannot be processed return an explicit error for that row.
-
4
Batch jobs
Submit large prediction jobs and retrieve results when they are complete.
POST /api/v1/batch-jobs GET /api/v1/batch-jobs/{batchJobId} POST /api/v1/batch-jobs/{batchJobId}/cancel GET /api/v1/batch-jobs/{batchJobId}/resultsJobs move through the states
validating,queued,running,completed,completed_with_errors,failed, andcancelled. -
5
Explanations
Request a per-prediction explanation after the fact. Explanations are computed on demand against the exact model version that made the prediction.
POST /api/v1/inference-records/{inferenceRecordId}/explanationsIf the original input was not retained, resubmit it against the model version:
POST /api/v1/models/{modelVersionId}/explanationsExplanations are available when they are enabled for the model.
-
6
Errors
Errors return an HTTP status and a consistent body with a stable code, a readable message, and the request’s correlation ID.
{ "error": { "code": "API_QUOTA_EXCEEDED", "message": "This API key has reached its configured request limit.", "correlationId": "req_12345" } }Error responses never include stack traces, host paths, or internal identifiers. Include the correlation ID when contacting support.
-
7
Quotas and usage
API quotas are set per key. When a key reaches its limit, further requests return
429withAPI_QUOTA_EXCEEDED. There is no automatic overage.Batch quotas are measured in rows and apply across your organization.
Per-key usage and error analytics are available in the platform.
Planning an integration?
Tell us where predictions need to show up in your systems. We will help your team plan the integration and get access to the full API reference.