Deploy API

The Deploy API provides HTTP endpoints for deploying, activating, and managing Vespa applications. It is primarily used by the Vespa CLI and deployment automation tools.

Base URL

http://<config-server-host>:19071/application/v2/

The Deploy API runs on the config server, typically on port 19071, not on the regular container port (8080).

Deployment Workflow

Deploying a Vespa application follows this workflow:

Upload: Upload application package as a ZIP
Prepare: Validate and prepare the application
Activate: Make the application live

Session Management

Vespa uses “sessions” to manage deployments. Each upload creates a new session that can be prepared and activated.

Upload Application Package

Upload an application package as a ZIP file.

curl -X POST \
  --header "Content-Type: application/zip" \
  --data-binary @application.zip \
  http://localhost:19071/application/v2/tenant/default/session

Request

tenant

string

default:"default"

Tenant name

Content-Type

string

required

Must be application/zip

Response

{
  "session-id": "123",
  "message": "Session created"
}

session-id

string

Unique session identifier for this deployment

message

string

Status message

Prepare Session

Prepare an uploaded session for activation.

curl -X PUT \
  http://localhost:19071/application/v2/tenant/default/session/123/prepared

Request Parameters

tenant

string

required

Tenant name

session-id

string

required

Session ID from upload

applicationName

string

default:"default"

Application name

instance

string

default:"default"

Instance name

timeout

string

default:"60s"

Preparation timeout

ignoreValidationErrors

boolean

default:"false"

Ignore non-critical validation errors

vespaVersion

string

Target Vespa version (defaults to current version)

Response

{
  "log": [
    {
      "time": 1640000000000,
      "level": "info",
      "message": "Preparing application"
    }
  ],
  "configChangeActions": {
    "restart": [],
    "refeed": [],
    "reindex": []
  },
  "tenant": "default",
  "session-id": "123",
  "message": "Session prepared"
}

log

array

Array of log messages from preparation

configChangeActions

object

Required actions for deployment

configChangeActions.restart

array

Services that need restart

configChangeActions.refeed

array

Document types that need refeeding

configChangeActions.reindex

array

Document types that need reindexing

Example: Prepare with Parameters

curl -X PUT "http://localhost:19071/application/v2/tenant/default/session/123/prepared?applicationName=myapp&timeout=120"

Activate Session

Activate a prepared session to make it live.

curl -X PUT \
  http://localhost:19071/application/v2/tenant/default/session/123/active

Request Parameters

tenant

string

required

Tenant name

session-id

string

required

Session ID to activate

timeout

string

default:"120s"

Activation timeout

ignoreSessionStaleFailure

boolean

default:"false"

Ignore stale session errors (not recommended for production)

Response

{
  "tenant": "default",
  "application": "default",
  "instance": "default",
  "session-id": "123",
  "message": "Session activated"
}

tenant

string

Tenant name

application

string

Application name

instance

string

Instance name

Application Management

Get Application Status

Get information about a deployed application.

curl http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default

Response

{
  "generation": 123,
  "applicationPackageFileReference": "abc123...",
  "versions": [
    {
      "generation": 123,
      "vespaVersion": "8.250.53"
    }
  ]
}

generation

integer

Current application generation (deployment version number)

applicationPackageFileReference

string

Reference to the application package

versions

array

Array of deployed versions

Delete Application

Delete a deployed application.

curl -X DELETE \
  http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default

Response

{
  "message": "Application deleted"
}

List Service Convergence

Check if services have converged to the latest configuration.

curl "http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/serviceconverge?timeout=60s"

timeout

string

default:"5s"

Maximum time to wait for convergence

vespaVersion

string

Check convergence for specific Vespa version

Response

{
  "url": "http://localhost:19071/application/v2/...",
  "currentGeneration": 123,
  "wantedGeneration": 123,
  "converged": true,
  "services": [
    {
      "host": "localhost",
      "port": 19100,
      "type": "searchnode",
      "clusterName": "content",
      "url": "http://localhost:19100/state/v1/config",
      "currentGeneration": 123
    }
  ]
}

converged

boolean

Whether all services have converged to wanted generation

currentGeneration

integer

Current config generation across all services

wantedGeneration

integer

Target config generation

services

array

List of services with their convergence status

Check Single Service Convergence

Check convergence for a specific service.

curl "http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/serviceconverge/localhost:19100"

Response

{
  "url": "http://localhost:19071/application/v2/...",
  "host": "localhost:19100",
  "wantedGeneration": 123,
  "converged": true,
  "currentGeneration": 123
}

Application Content

Get Application Files

Retrieve files from the deployed application package.

# List directory contents
curl http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/content/

# Get specific file
curl http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/content/services.xml

Response (directory listing)

[
  {
    "name": "services.xml",
    "type": "file",
    "size": 1234
  },
  {
    "name": "schemas",
    "type": "directory"
  }
]

Restart Operations

Restart Services

Restart services in the application.

# Restart all services
curl -X POST \
  http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/restart

# Restart specific host
curl -X POST \
  "http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/restart?hostname=host1.example.com"

hostname

string

Restart only services on specific host

clusterId

string

Restart only services in specific cluster

clusterType

string

Restart only services of specific type (e.g., content, container)

Response

{
  "message": "Success"
}

Reindexing Operations

Trigger Reindexing

Trigger reindexing of documents.

curl -X POST \
  "http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/reindex?clusterId=content&documentType=music"

clusterId

string

Target cluster (required for specific document types)

documentType

string

Specific document type to reindex

indexedOnly

boolean

default:"false"

Only reindex indexed document types

speed

number

default:"1.0"

Reindexing speed multiplier (0.0-100.0)

cause

string

Reason for reindexing (for logging)

Get Reindexing Status

Check status of ongoing reindexing.

curl http://localhost:19071/application/v2/tenant/default/application/default/environment/prod/region/default/instance/default/reindexing

Response

{
  "enabled": true,
  "clusters": {
    "content": {
      "pending": [],
      "ready": {
        "music": {
          "startedMillis": 1640000000000,
          "endedMillis": 1640003600000,
          "state": "successful",
          "progress": 1.0
        }
      }
    }
  }
}

Complete Deployment Example

#!/bin/bash

CONFIG_SERVER="http://localhost:19071"
TENANT="default"
APP_NAME="myapp"
APP_ZIP="application.zip"

# Step 1: Upload application package
echo "Uploading application package..."
SESSION_RESPONSE=$(curl -s -X POST \
  --header "Content-Type: application/zip" \
  --data-binary @${APP_ZIP} \
  "${CONFIG_SERVER}/application/v2/tenant/${TENANT}/session")

SESSION_ID=$(echo $SESSION_RESPONSE | jq -r '.["session-id"]')
echo "Session ID: ${SESSION_ID}"

# Step 2: Prepare session
echo "Preparing session..."
PREPARE_RESPONSE=$(curl -s -X PUT \
  "${CONFIG_SERVER}/application/v2/tenant/${TENANT}/session/${SESSION_ID}/prepared?applicationName=${APP_NAME}")

echo "Prepare response: ${PREPARE_RESPONSE}"

# Step 3: Activate session
echo "Activating session..."
ACTIVATE_RESPONSE=$(curl -s -X PUT \
  "${CONFIG_SERVER}/application/v2/tenant/${TENANT}/session/${SESSION_ID}/active")

echo "Activate response: ${ACTIVATE_RESPONSE}"

# Step 4: Wait for convergence
echo "Waiting for services to converge..."
while true; do
  CONVERGE_RESPONSE=$(curl -s \
    "${CONFIG_SERVER}/application/v2/tenant/${TENANT}/application/${APP_NAME}/environment/prod/region/default/instance/default/serviceconverge?timeout=30s")
  
  CONVERGED=$(echo $CONVERGE_RESPONSE | jq -r '.converged')
  
  if [ "$CONVERGED" = "true" ]; then
    echo "All services converged!"
    break
  fi
  
  echo "Waiting for convergence..."
  sleep 5
done

echo "Deployment complete!"

Using Vespa CLI

For most deployments, use the Vespa CLI instead of calling the API directly:

# Deploy application
vespa deploy

# Wait for convergence
vespa status

# Deploy to Vespa Cloud
vespa deploy --wait 300

Error Handling

Common Errors

Status	Error	Solution
400	Invalid application package	Check application package structure and validation errors
409	Session already active	Session is already activated or being processed
412	Preparation failed	Fix validation errors reported in response
504	Timeout	Increase timeout parameter or check service health

Error Response Example

{
  "error-code": "BAD_REQUEST",
  "message": "Invalid application package: Schema validation failed"
}

Security

In production environments, the Deploy API should be protected with authentication and restricted network access.

Vespa Cloud

Vespa Cloud automatically handles authentication via:

mTLS certificates for API access
Integration with CI/CD through API keys

Self-Hosted

For self-hosted deployments:

Use firewall rules to restrict access to port 19071
Implement reverse proxy with authentication
Use VPN for remote deployments

HTTP APIs

Java APIs

Client Libraries

Base URL

Deployment Workflow

Session Management

Upload Application Package

Prepare Session

Activate Session

Application Management

Get Application Status

Delete Application

List Service Convergence

Check Single Service Convergence

Application Content

Get Application Files

Restart Operations

Restart Services

Reindexing Operations

Trigger Reindexing

Get Reindexing Status

Complete Deployment Example

Using Vespa CLI

Error Handling

Common Errors

Security

Vespa Cloud

Self-Hosted

Build docs developers (and LLMs) love

HTTP APIs

Java APIs

Client Libraries

​Base URL

​Deployment Workflow

​Session Management

​Upload Application Package

​Prepare Session

​Activate Session

​Application Management

​Get Application Status

​Delete Application

​List Service Convergence

​Check Single Service Convergence

​Application Content

​Get Application Files

​Restart Operations

​Restart Services

​Reindexing Operations

​Trigger Reindexing

​Get Reindexing Status

​Complete Deployment Example

​Using Vespa CLI

​Error Handling

​Common Errors

​Security

​Vespa Cloud

​Self-Hosted

​Related Documentation

Build docs developers (and LLMs) love

Base URL

Deployment Workflow

Session Management

Upload Application Package

Prepare Session

Activate Session

Application Management

Get Application Status

Delete Application

List Service Convergence

Check Single Service Convergence

Application Content

Get Application Files

Restart Operations

Restart Services

Reindexing Operations

Trigger Reindexing

Get Reindexing Status

Complete Deployment Example

Using Vespa CLI

Error Handling

Common Errors

Security

Vespa Cloud

Self-Hosted

Related Documentation