Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Activate a Service Revision with the REST APIBeta

Beta
This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

Activate a revision of a service from a script or CI job, and find out whether it went live or is waiting for quality checks.

About This Task​

Some services test every new revision before it goes live. That test is called a Deployment Gate, and it works like a release gate in a CI/CD workflow. When you activate a revision on such a service, it doesn't serve requests right away. The platform holds it while the checks run, and the service keeps answering with its current revision until they pass. Services without a gate activate revisions immediately.

The hold applies when you activate a revision that was never active before. It also applies when you re-activate a service that has never had an active or pending revision. Re-activating a revision that was active before isn't held.

In the API, a service is called a deployment. Currently, you create gates only with the REST API. To learn what a gate checks, see Deployment Gates.

Prerequisites​

  • You need a Haystack Platform API key. For details, see Generate API Keys.
  • You need the ID of the service and the ID of the revision you want to activate.

Activate a Revision​

Send a POST request to Activate Deployment Revision. Replace <YOUR_WORKSPACE>, <DEPLOYMENT_ID>, <REVISION_ID>, and <YOUR_API_KEY> with your values:

curl --request POST \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE>/deployments/<DEPLOYMENT_ID>/revisions/<REVISION_ID>/activate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>'

To activate a service that has no revision yet, use Activate Deployment instead.

If a gate holds the revision, the response contains a deployment_gate_result_id. Keep it to follow the result.

Follow a Held Revision​

To find out whether the held revision passed, read its Gate Result. Replace <DEPLOYMENT_GATE_RESULT_ID> with the ID from the previous step:

curl --request GET \
     --url https://api.cloud.deepset.ai/api/v1/workspaces/<YOUR_WORKSPACE>/deployments/<DEPLOYMENT_ID>/gate-results/<DEPLOYMENT_GATE_RESULT_ID> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>'

The Gate Result gives the status of the run, the checks it judged, the verdict of each check once the run has decided, and the error if the run failed. It also gives the replay suite of each Dataset and the Scoring Run of each Metric Group, so you can open them to see why a check passed or failed.

  • The run passes: the revision activates.
  • The run is still going: the service keeps serving its current revision. Send the request again later to check progress.
  • The run fails: read the error and the checks in the Gate Result to see why. The service keeps serving its current revision.

The request returns a 404 error if the service or the Gate Result doesn't exist. To read a result in the UI instead, see Check If a Revision Went Live.

Fix a Refused Activation​

The platform refuses the activation when the gate can't vouch for the revision:

  • 409 with gate_run_in_flight: a gate run for this service is still running. Wait for it to finish, then try again.
  • 409 with gate_draft_version: the gate can't judge a draft pipeline version. Use a published version.
  • 409 with gate_revision_config_mismatch: the revision's configuration doesn't match the pipeline version the gate would replay. Create the revision again from the pipeline version you want to serve.
  • 422 with gate_requires_platform_revision: the revision doesn't run a pipeline built on the platform, so there's nothing to replay. Gated services accept only platform pipeline revisions.

A service with a gate also doesn't accept an optimization suggestion directly. The accept request returns 409 with gate_blocks_optimization_accept, because the suggestion would change the served configuration without going through the gate. Deploy the candidate's pipeline version through the service so the gate judges it.