---
title: "Live API Examples | DreamFactory Docs"
source: "https://docs.dreamfactory.com/api-reference/system-api-examples"
canonical_url: "https://docs.dreamfactory.com/api-reference/system-api-examples"
converted_at: "2026-04-04T08:25:59.543Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
>
> All examples verified against a live DreamFactory 7.4.2 instance. Responses are real, trimmed for brevity.
>
>
>

>
> ⚠️ **Shell quoting gotcha:** Using `-d '{"email":...}'` can silently fail on some shells — the JSON body arrives but DF doesn't parse it. Always use `-d @file.json` for reliability.
>
>
>

---

## Setup[​](#setup)

```
APIKEY="your-admin-app-api-key"# Write payload to file — avoids shell quoting issuescat > /tmp/login.json << 'EOF'{"email":"[email protected]","password":"yourpassword"}EOFTOKEN=$(curl -s -X POST http://your-df-host/api/v2/system/admin/session \  -H "Content-Type: application/json" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -d @/tmp/login.json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_token'])")
```

---

## System Info[​](#system-info)

### Get DF Version and Environment[​](#get-df-version-and-environment)

```
curl -s http://your-df-host/api/v2/system/environment \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response (trimmed):**

```
{  "platform": {    "version": "7.4.2",    "is_hosted": false  }}
```

---

## Service Management[​](#service-management)

### List All Services[​](#list-all-services)

```
curl -s "http://your-df-host/api/v2/system/service?fields=id,name,type,label" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response:**

```
{  "resource": [    {"id": 1, "name": "system",   "type": "system",      "label": "System Management"},    {"id": 2, "name": "api_docs", "type": "swagger",     "label": "Live API Docs"},    {"id": 3, "name": "files",    "type": "local_file",  "label": "Local File Storage"},    {"id": 4, "name": "logs",     "type": "local_file",  "label": "Local Log Storage"},    {"id": 5, "name": "db",       "type": "sqlite",      "label": "Local SQL Database"},    {"id": 6, "name": "email",    "type": "local_email", "label": "Local Email Service"},    {"id": 7, "name": "user",     "type": "user",        "label": "User Management"}  ]}
```

The `name` field becomes the URL namespace: `/api/v2/{name}/`.

### List All Available Service Types[​](#list-all-available-service-types)

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

**Real response — use `name` as the `type` field when creating services:**

namelabelgroup`mysql`MySQLDatabase`pgsql`PostgreSQLDatabase`sqlite`SQLiteDatabase`mssql`MS SQL ServerDatabase`alloydb`AlloyDBDatabase`aws_dynamodb`AWS DynamoDBDatabase`aws_redshift_db`AWS RedshiftDatabase`cassandra`CassandraDatabase`couchdb`CouchDBDatabase`azure_documentdb`Azure DocumentDBDatabase`azure_table`Azure Table StorageDatabase`firebird`FirebirdDatabase`aws_s3`AWS S3File`azure_blob`Azure Blob StorageFile`local_file`Local File StorageFile`ftp_file`FTP File StorageFile`sftp_file`SFTP File StorageFile`webdav_file`WebDAV File StorageFile`openstack_object_storage`OpenStack Object StorageFile`rackspace_cloud_files`Rackspace Cloud FilesFile`rws`HTTP ServiceRemote Service`mcp`MCP Server ServiceMCP`aws_ses`AWS SESEmail`local_email`Local Email ServiceEmail`mailgun_email`MailgunEmail`smtp_email`SMTPEmail`aws_sns`AWS SNSNotification`oauth_github`GitHub OAuthOAuth`oauth_google`Google OAuthOAuth`oauth_facebook`Facebook OAuthOAuth`oauth_microsoft-live`Microsoft Live OAuthOAuth`cache_redis`RedisCache`cache_memcached`MemcachedCache`amqp`AMQP ClientIoT`mqtt`MQTT ClientIoT

### Create a MySQL Service[​](#create-a-mysql-service)

```
cat > /tmp/mysql_svc.json << 'EOF'{  "resource": [{    "name": "mysql",    "label": "MySQL Database",    "type": "mysql",    "is_active": true,    "config": {      "host": "mysql",      "port": 3306,      "database": "mydb",      "username": "myuser",      "password": "mypassword"    }  }]}EOFcurl -s -X POST http://your-df-host/api/v2/system/service \  -H "Content-Type: application/json" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN" \  -d @/tmp/mysql_svc.json
```

**Real response:**

```
{"resource": [{"id": 12}]}
```

Returns just the new service ID. Use it for updates/deletes: `PATCH /api/v2/system/service/12`.

### Create a PostgreSQL Service[​](#create-a-postgresql-service)

```
cat > /tmp/pgsql_svc.json << 'EOF'{  "resource": [{    "name": "world",    "label": "World (Sample Data)",    "type": "pgsql",    "is_active": true,    "config": {      "host": "example_data",      "port": 5432,      "database": "world",      "username": "postgres",      "password": "root_pw"    }  }]}EOFcurl -s -X POST http://your-df-host/api/v2/system/service \  -H "Content-Type: application/json" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN" \  -d @/tmp/pgsql_svc.json
```

### Delete a Service[​](#delete-a-service)

```
curl -s -X DELETE "http://your-df-host/api/v2/system/service?ids=12" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

---

## App Management[​](#app-management)

### List Apps (includes API keys)[​](#list-apps-includes-api-keys)

```
curl -s "http://your-df-host/api/v2/system/app?fields=id,name,api_key,is_active" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response:**

```
{  "resource": [    {"id": 1, "name": "admin",        "api_key": "6498a8ad...", "is_active": true},    {"id": 2, "name": "api_docs",     "api_key": "36fda24f...", "is_active": true},    {"id": 3, "name": "file_manager", "api_key": "b5cb82af...", "is_active": true}  ]}
```

The `admin` app's `api_key` is the one to use for `X-DreamFactory-API-Key` in admin operations.

---

## API Discovery[​](#api-discovery)

### Get OpenAPI Spec for a Service (DF 7.4.x)[​](#get-openapi-spec-for-a-service-df-74x)

```
curl -s http://your-df-host/api/v2/api_docs/world \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

Returns a full OpenAPI 3.0 spec. The `world` service has 14 paths covering `_schema` and `_table` operations.

First 5 paths:

```
GET/POST/PUT/PATCH  /_schemaGET/POST/PUT/PATCH/DELETE  /_schema/{table_name}GET/POST/PUT/PATCH/DELETE  /_schema/{table_name}/_fieldGET  /_schema/{table_name}/_relatedGET/POST/PUT/PATCH/DELETE  /_table/{table_name}
```

### Get Spec for System API[​](#get-spec-for-system-api)

```
curl -s http://your-df-host/api/v2/api_docs/system \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

Returns 32 paths covering all system management operations.

---

## Data Queries[​](#data-queries)

All examples use the `world` PostgreSQL service (3 tables: `country`, `city`, `countrylanguage`).

### List Tables[​](#list-tables)

```
curl -s "http://your-df-host/api/v2/world/_schema?fields=name" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response:**

```
{  "resource": [    {"name": "city"},    {"name": "country"},    {"name": "countrylanguage"}  ]}
```

### Basic Query with Field Selection[​](#basic-query-with-field-selection)

```
curl -s "http://your-df-host/api/v2/world/_table/country?limit=3&fields=Code,Name,Continent,Population" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response:**

```
{  "resource": [    {"code": "AFG", "name": "Afghanistan",          "continent": "Asia",          "population": 22720000},    {"code": "NLD", "name": "Netherlands",           "continent": "Europe",        "population": 15864000},    {"code": "ANT", "name": "Netherlands Antilles",  "continent": "North America", "population": 217000}  ]}
```

### Filter + Sort + Limit[​](#filter--sort--limit)

```
curl -s "http://your-df-host/api/v2/world/_table/country?filter=Continent%3D'Asia'&order=Population%20DESC&limit=5&fields=Name,Continent,Population,LifeExpectancy" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response:**

```
{  "resource": [    {"name": "China",       "continent": "Asia", "population": 1277558000, "lifeexpectancy": 71.4},    {"name": "India",       "continent": "Asia", "population": 1013662000, "lifeexpectancy": 62.5},    {"name": "Indonesia",   "continent": "Asia", "population": 212107000,  "lifeexpectancy": 68.0},    {"name": "Pakistan",    "continent": "Asia", "population": 156483000,  "lifeexpectancy": 61.1},    {"name": "Bangladesh",  "continent": "Asia", "population": 129155000,  "lifeexpectancy": 60.2}  ]}
```

Filter syntax: `field=value`, `field>value`, `field LIKE '%pattern%'`, `field IN (a,b,c)`. URL-encode special chars.

### Get Single Record by ID[​](#get-single-record-by-id)

```
curl -s "http://your-df-host/api/v2/world/_table/country/USA?fields=Name,Code,Continent,Population,LifeExpectancy" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

**Real response:**

```
{  "name": "United States",  "code": "USA",  "continent": "North America",  "population": 278357000,  "lifeexpectancy": 77.1}
```

Single-record response is unwrapped (no `resource` array).

### Create a Record[​](#create-a-record)

```
cat > /tmp/new_record.json << 'EOF'{  "resource": [{    "name": "John Doe",    "email": "[email protected]"  }]}EOFcurl -s -X POST http://your-df-host/api/v2/myservice/_table/contacts \  -H "Content-Type: application/json" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN" \  -d @/tmp/new_record.json
```

**Response:** `{"resource": [{"id": 42}]}` — returns the new record's primary key.

### Update a Record[​](#update-a-record)

```
cat > /tmp/update.json << 'EOF'{"email": "[email protected]"}EOFcurl -s -X PATCH http://your-df-host/api/v2/myservice/_table/contacts/42 \  -H "Content-Type: application/json" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN" \  -d @/tmp/update.json
```

### Delete Records[​](#delete-records)

```
# By IDcurl -s -X DELETE "http://your-df-host/api/v2/myservice/_table/contacts?ids=1,2,3" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"# By filtercurl -s -X DELETE "http://your-df-host/api/v2/myservice/_table/contacts?filter=status%3D'inactive'" \  -H "X-DreamFactory-API-Key: $APIKEY" \  -H "X-DreamFactory-Session-Token: $TOKEN"
```

---

## Query Parameter Reference[​](#query-parameter-reference)

ParamExampleDescription`fields``fields=id,name,email`Return only these fields. `*` = all.`filter``filter=status='active'`SQL-like filter. URL-encode `=`, spaces, quotes.`order``order=name ASC`Sort field + direction. URL-encode space.`limit``limit=25`Max records. Default varies by config.`offset``offset=50`Skip N records (for pagination).`include_count``include_count=true`Add `meta.count` with total matching records.`related``related=city_by_CountryCode`Join related table. Name format: `{table}_by_{fk_field}`.`ids``ids=1,2,3`Fetch specific records by primary key.

---

## Notes for LLMs[​](#notes-for-llms)

1. **Always use `-d @file.json`** for POST/PATCH bodies. Inline `-d '...'` has shell quoting edge cases that silently drop the body.

2. **Token expires in 24h.** Re-POST to `/api/v2/system/admin/session` to refresh.

3. **Field names are lowercased** in responses even if the DB uses uppercase (e.g., `Code` → `code`).

4. **Single vs list responses:** By-ID requests return the object directly. List requests return `{"resource": [...]}`.

5. **Check the live spec first:** `GET /api/v2/api_docs/{service_name}` gives you the exact schema for any service before you start querying.