Skip to main content

API Discovery & Spec Endpoints

DreamFactory exposes OpenAPI 3.0 specs for every service. This is the first thing an LLM or programmatic client should do — discover what's available and read the spec before making calls. If you want to generate a database-backed REST API, DreamFactory can auto-create all endpoints from your existing schema.

Step 1: List All Services​

curl -s http://your-df-host/api/v2/system/service \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN" \
  | python3 -c "
import sys, json
for s in json.load(sys.stdin)['resource']:
    print(s['name'], '-', s['type'], '-', s['label'])
"

This gives you every service name — used as the URL namespace in /api/v2/{name}/.

Step 2: Get the OpenAPI Spec for a Service​

DF 7.5+ (newer versions)​

Each service exposes its own spec directly:

GET /api/v2/{service_name}/_spec
curl -s http://your-df-host/api/v2/system/_spec \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

DF 7.4.x and earlier​

Use the api_docs service instead:

GET /api/v2/api_docs/{service_name}
# Full system API spec
curl -s http://your-df-host/api/v2/api_docs/system \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

# Spec for a database service named 'mysql'
curl -s http://your-df-host/api/v2/api_docs/mysql \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

Get all specs at once​

# Full combined spec for all services
curl -s http://your-df-host/api/v2/api_docs \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

Step 3: Extract Paths from Spec​

import requests, json

APIKEY = "your-api-key"
TOKEN = "your-session-token"
HOST = "http://your-df-host"

# Get spec for a service
spec = requests.get(
    f"{HOST}/api/v2/api_docs/system",
    headers={
        "X-DreamFactory-API-Key": APIKEY,
        "X-DreamFactory-Session-Token": TOKEN,
    }
).json()

# List all endpoints
for path, methods in sorted(spec["paths"].items()):
    for method in methods:
        if method in ["get", "post", "put", "patch", "delete"]:
            summary = methods[method].get("summary", "")
            print(f"{method.upper():7} /api/v2{path}  —  {summary}")

What the Spec Tells You​

Each path entry includes:

  • summary — one-line description
  • description — full explanation
  • parameters — query params with types and descriptions
  • requestBody — $ref to schema in components/schemas
  • responses — response schemas

The components/schemas section has the full field definitions for every request and response object.

Check DF Version​

curl -s http://your-df-host/api/v2/system/environment \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN" \
  | python3 -c "import sys,json; e=json.load(sys.stdin); print(e['platform']['version'])"
  • 7.5+: Use GET /api/v2/{service}/_spec
  • 7.4.x and earlier: Use GET /api/v2/api_docs/{service}

Available Service Types​

To see all service types you can create:

curl -s http://your-df-host/api/v2/system/service_type?fields=name,label,group \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

This returns the valid type values for POST /api/v2/system/service.

Retrieving OpenAPI Specs — Code Examples​

Once you know a service name, you can retrieve its OpenAPI spec programmatically. The examples below work for both LLM agents and developer tooling.

cURL​

# DF 7.5+ — fetch the spec for a service named 'mysql'
curl -s http://your-df-host/api/v2/mysql/_spec \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

# DF 7.4.x and earlier — use api_docs
curl -s http://your-df-host/api/v2/api_docs/mysql \
  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \
  -H "X-DreamFactory-Session-Token: YOUR_TOKEN"

JavaScript (fetch)​

const DF_HOST = 'http://your-df-host';
const SERVICE = 'mysql';
const headers = {
  'X-DreamFactory-API-Key': 'YOUR_API_KEY',
  'X-DreamFactory-Session-Token': 'YOUR_TOKEN',
};

// DF 7.5+ endpoint
const response = await fetch(`${DF_HOST}/api/v2/${SERVICE}/_spec`, { headers });
const spec = await response.json();

// Print all available paths
Object.keys(spec.paths).forEach(path => console.log(path));

Both approaches return an OpenAPI 3.0 document you can feed directly to an LLM context window, an API client generator, or a documentation tool.

Troubleshooting​

Spec endpoint returns 403​

A 403 response means the API key or session token you are using is bound to a role that does not have access to the spec endpoint for that service.

Fix: In the DreamFactory admin panel, open the role attached to your API key, navigate to Access Overview, and ensure the target service is listed with at least GET access on the _spec component (or * for all components). See Role-Based Access Control for details.

Spec shows empty paths object​

An OpenAPI document with paths: {} means the service was found but has no routable endpoints. This usually means the service is not fully activated or its underlying connection is broken.

Fix: Navigate to API Generation & Connections in the admin panel, open the service, and verify the connection test passes. For database services, confirm the database is reachable and credentials are correct.

Endpoint not found (404)​

A 404 on the spec URL usually means the service name in the URL does not match any configured service.

Fix: Run the Step 1 listing call to retrieve exact service names, then substitute the correct name value (case-sensitive) into your spec URL.