​ValidMind Public REST API

Published

July 31, 2026

The ValidMind Platform provides a RESTful APIs to programmatically interact with:

Base URL

https://api.prod.validmind.ai/vm/api/v1/

Versioning

This version of the API is v1, specified in the path (/vm/api/v1). Future breaking changes will be introduced under a new version path.

Authentication

You can authenticate Public REST API requests with API keys or, when your organization enables it, an OIDC bearer access token.

NoteAvailability of OIDC

OIDC bearer auth for the Public REST API depends on your organization’s API connectivity settings. If bearer requests return 403, your organization may require API keys only — contact your ValidMind administrator.

Required headers

Include both headers with every request:

  • x-api-key: Your ValidMind API key
  • x-api-secret: Your ValidMind API secret

Request example

To use this cURL example, replace API_KEY and API_SECRET with your own credentials:

curl -X GET "https://api.prod.validmind.ai/vm/api/v1/models" \
  -H 'accept: application/json' \
  -H 'x-api-key: API_KEY' \
  -H 'x-api-secret: API_SECRET'

Get your API key and secret

  1. In the left sidebar, click Settings.

  2. Under Your Account, select Profile.

  3. Under Access Keys:

    • Locate API Key and click Copy to Clipboard.
    • Locate Secret Key and click Copy to Clipboard.

Required headers

Include an OIDC access token obtained from your organization’s identity provider (for example via the OAuth 2.0 device authorization flow):

  • Authorization: Bearer <access_token>

If your user belongs to more than one organization, also include:

  • X-Organization-Id: <organization-cuid>

When you belong to exactly one organization, you can omit X-Organization-Id and the API uses that membership.

Do not send API key headers together with a bearer token for the same request. Use one authentication mode at a time.

Request example

curl -X GET "https://api.prod.validmind.ai/vm/api/v1/models" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Id: ORGANIZATION_CUID'

Replace ACCESS_TOKEN with a valid OIDC access token for your ValidMind deployment, and ORGANIZATION_CUID when you need to select an organization.

For library sessions that use the same device-flow pattern in Python notebooks, see Authenticate with OIDC device flow. Public API callers obtain and refresh tokens with their IdP client, then pass the access token in the Authorization header as shown above.

Data formats

The APIs follows REST principles and uses JSON for both requests and responses.

  • All endpoints consume and produce application/json.
  • CSV format is optionally supported for some listing endpoints using the format=csv query parameter.

Common response codes

Code Meaning
200 Success
400 Bad request (validation)
401 Authentication failed
403 Authorization failed
404 Resource not found
500 Internal server error

Reference