API

This page provides a brief overview of the NVCF API. All API endpoints are served through your gateway. See gateway-routing for details on configuring your gateway domain and DNS.

OpenAPI Specification

This page does not cover all endpoints.

Please refer to the OpenAPI Spec for the latest API information.

The self-hosted API surface is divided into the following sets of APIs:

API versioning

All API endpoints include versioning in the path prefix.

/v2/nvcf
/v3/ledger

The NVCF OpenAPI specification does not include the separate Event Ledger v3 API. See Event Ledger for its supported endpoints, query parameters, response fields, and producer interfaces.

Authorization

Self-hosted NVCF uses four bearer credential types:

All four credential types are sent as bearer credentials:

Authorization: Bearer <credential>

Use the CLI for normal credential management:

nvcf-cli init
nvcf-cli api-key generate

nvcf-cli init calls the API Keys admin endpoint and mints the JWT used as NVCF_TOKEN. The CLI saves the token in ~/.nvcf-cli.state for the default configuration and reads it automatically on later commands. Export it only when you are making direct API calls or using tooling that reads environment variables:

export NVCF_TOKEN=$(jq -r .token ~/.nvcf-cli.state)

The default self-hosted admin issuer role gives this token the following scopes:

• register_function
• list_functions
• list_functions_details
• deploy_function
• update_function
• update_secrets
• delete_function
• manage_telemetries
• manage_registry_credentials
• cluster-management

The function API key (NVCF_API_KEY) is created with these default scopes:

• invoke_function
• list_functions
• queue_details
• list_functions_details
• manage_telemetries

The task API key (NVCF_NVCT_API_KEY) is created with these default scopes:

• launch_task
• list_tasks
• task_details
• cancel_task
• delete_task
• list_events
• list_results
• update_secrets

The Event Ledger API key (EVENT_LEDGER_API_KEY) is created with the fnds:getEvents scope. It has an Event Ledger-specific audience. Function and task API keys are not used as fallbacks for Event Ledger reads.

NVCF API authorization is scope-based. For the NVCF API endpoints below, either NVCF_TOKEN or NVCF_API_KEY can be used if that bearer includes the required scope. The CLI prefers NVCF_API_KEY for read, invoke, and queue commands. It prefers NVCF_TOKEN for management commands when both credentials are configured.

Pass --scopes when you need to narrow a key or create a key with management scopes for testing.

Scope reference

The OpenAPI spec describes the permission checked for each endpoint. “Accepted bearer” means which saved CLI credential type can be sent as Authorization: Bearer <credential> when it includes the listed scope.

Self-hosted cluster management uses SIS endpoints from the Spot API. In self-hosted CLI workflows, use NVCF_TOKEN with the cluster-management scope for these endpoints.

Task management uses NVCT endpoints served through your gateway. All task endpoints require NVCF_NVCT_API_KEY with the listed scope.

Event Ledger uses v3 endpoints served through the events.<domain> gateway route. Read endpoints require EVENT_LEDGER_API_KEY with the fnds:getEvents scope. Service credentials that publish events require fnds:createEvent. An authorized NVCA projected token can also publish after its cluster identity is verified.

See Event Ledger for context matching and filtering rules.

Direct API key creation

The CLI calls the API Keys service for you. If you need to call it directly, set expires_at and the scopes array explicitly.

GATEWAY_ADDR=<your-gateway-address>
EXPIRES_AT=$(date -u -v+1d '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || date -u -d '+1 day' '+%Y-%m-%dT%H:%M:%SZ')
SERVICE_ID="nvidia-cloud-functions-ncp-service-id-aketm"
curl -s -X POST "http://${GATEWAY_ADDR}/v1/keys" \
  -H "Host: api-keys.${GATEWAY_ADDR}" \
  -H "Content-Type: application/json" \
  -H "Key-Issuer-Service: nvcf-api" \
  -H "Key-Issuer-Id: ${SERVICE_ID}" \
  -H "Key-Owner-Id: test@nvcf-api.local" \
  -d '{
    "description": "invocation key",
    "expires_at": "'"${EXPIRES_AT}"'",
    "authorizations": {
      "policies": [{
        "aud": "'"${SERVICE_ID}"'",
        "auds": ["'"${SERVICE_ID}"'"],
        "product": "nv-cloud-functions",
        "resources": [
          {"id": "*", "type": "account-functions"},
          {"id": "*", "type": "authorized-functions"}
        ],
        "scopes": ["invoke_function", "list_functions", "queue_details", "list_functions_details"]
      }]
    },
    "audience_service_ids": ["'"${SERVICE_ID}"'"]
  }' | jq .