ProductOverviewHow It WorksCapabilitiesFor Your Team
TrustOverviewData Protection & GovernanceSecurity & AccessOwnership & ConfidentialityAudit & Accountability
ResourcesTechnical OverviewAPI OverviewSupport
CompanyAbout AscentMLContactRed Mountain Innovations
Talk to AscentML

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. 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. 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. 3

    Real-time inference

    Choose the endpoint that matches how you want to select a model.

    Through a deployment

    POST /api/v1/deployments/{deploymentId}/inference

    Recommended 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}/inference

    Against a specific model version

    POST /api/v1/models/{modelId}/versions/{versionId}/inference

    Useful 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. 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}/results

    Jobs move through the states validating, queued, running, completed, completed_with_errors, failed, and cancelled.

  5. 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}/explanations

    If the original input was not retained, resubmit it against the model version:

    POST /api/v1/models/{modelVersionId}/explanations

    Explanations are available when they are enabled for the model.

  6. 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. 7

    Quotas and usage

    API quotas are set per key. When a key reaches its limit, further requests return 429 with API_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.