API

In here you’ll find some practical API examples. But first, let’s explain how to authenticate.

Looking for the full endpoint list?

On FOG 1.6 and newer the server describes its own API. API Documentation in the main menu renders every endpoint your install exposes, with field types, the permission each one needs, and a working try it console. The same document is machine-readable at /fog/swagger.json, so you can generate a client from it in any language. See API Documentation Page & OpenAPI Spec.

That reference is generated from the running server, so it stays accurate as classes and routes change. The examples below are still the best starting point for how to call the API; the generated document is where to look up what is callable.

Basics

To be able to use the API via external calls it needs to be enabled in the FOG web UI (FOG Configuration → FOG Settings → API System) first.

Authentication

There are three ways to authenticate. Pick one — you do not combine them.

Method	What you send	Also needs fog-api-token?
Bearer token (recommended)	Authorization: Bearer fog_<api token>	no
Token pair	fog-api-token + fog-user-token headers	yes
HTTP Basic	Authorization: Basic <base64 user:password>	yes

Every method carries the same permissions: the acting user’s roles are applied either way, so a user without user.view gets 403 Forbidden from /fog/user however they signed in.

Bearer token (recommended)

An API token is issued from the web UI, shown to you once, and sent in the standard Authorization header. Nothing else is required:

curl -H 'Authorization: Bearer fog_1a2b3c...' \
     -X GET http://fogserver/fog/host

API tokens are a separate credential from the User API Token described under Token pair below — they are not two spellings of the same thing. An API token is:

• stored hashed. The server keeps only a SHA-256 of it, so the token cannot be read back out of the database or the UI.
• shown once, at the moment you create it. If you lose it, delete it and issue another; there is no way to recover it.
• individually revocable. Each token has its own enable/disable switch, independent of the user’s User API Enable checkbox.
• one of many. Issue a separate token per script, host or integration, and retire one without disturbing the others.
• 512 bits of random, prefixed fog_ so it is recognisable on sight in a log, a config file or a support ticket.

Issuing one

Users → List All Users → your username → API, then use the API Tokens card at the bottom of that tab. Give the token a name describing what will use it — that name is all you will have to go on later when deciding whether a token is still needed.

The token is displayed once, immediately after creation. Copy it then.

Send the API token exactly as shown — do not base64-encode it

This is the opposite of the token pair below. The fog-api-token and fog-user-token headers carry base64 values, because that is the form the UI displays them in. An API token is sent raw, exactly as the UI showed it, fog_ prefix included. Encoding it first will fail with 401 Unauthorized.

The same card lists your existing tokens with their creation date and when each was last used, so a token nothing has touched in months is easy to spot and delete. Deleting a user deletes that user’s tokens with it.

Bearer with nothing after it

If you build the header from a config value that turns out to be unset, you send a bare Authorization: Bearer. FOG answers 401 Unauthorized for that specifically, rather than falling through to another method — so a 401 on a request you believe is authenticated is worth checking for an empty token variable.

Availability

API tokens are available from FOG 1.6.0. On older servers, and on 1.5.x, use the token pair below — see the 1.5 version of this page. Both older methods keep working on 1.6 and are not deprecated — nothing you have already built needs to change.

If you tried Bearer authentication on an early 1.6.0 beta: briefly, the User API Token was accepted as a Bearer value. It no longer is — a plaintext, UI-visible, non-revocable secret gave the Bearer scheme none of the properties listed above. Issue an API token from the card described here, or keep using that token in the header pair, where it is unchanged.

Token pair

FOG 1.6

This section, and HTTP Basic below, work exactly the same on FOG 1.5, which has no Bearer token option — see the 1.5 version of this page.

The original scheme, and the one to use on 1.5.x. Both headers are required together.

API global token — a header named fog-api-token. You can find yours via FOG Configuration → FOG Settings → API System.

API user token — a header named fog-user-token. You can find yours via Users → List All Users → your username → API. The user’s User API Enable checkbox on that tab must be ticked, or the token is rejected even when sent.

This is not the same credential as an API token. The two are separate, with separate properties; see Bearer token above. This one is unchanged from 1.5.x and keeps working exactly as it always has.

Copy the token values as shown

The web UI already displays both tokens base64-encoded, which is exactly the form the server expects in the header. Copy the displayed value verbatim — the server base64-decodes the header before comparing it. A raw, un-encoded token will fail with 403 Forbidden.

HTTP Basic Auth

You can use HTTP Basic Authorization (with curl -u <user>:<password> or a header of the form Authorization: Basic <base64encoded username:password>). Although this type of authentication is allowed and will work, the user-token system is still recommended, as a token cannot be decoded back into a valid username/password pair capable of managing your FOG server.

Basic auth replaces the user token, not the global one. The fog-api-token header is still required, and a request without it is rejected with 403 Forbidden before the username and password are ever looked at:

curl -H 'fog-api-token: yourapitoken' \
     -u 'youruser:yourpassword' \
     -X GET http://fogserver/fog/host

The account signs in exactly as it would in the web UI, so its roles apply the same way. A user whose roles do not include user.view gets 403 Forbidden from /fog/user whether they authenticated by token or by password. Accounts from an external directory (LDAP) can authenticate this way too, provided Allow API is enabled on the LDAP server.

Upgrading an existing server: re-run the installer

Basic auth and Bearer both depend on the Authorization header reaching PHP, and under FastCGI it does not arrive on its own — nginx forwards only a fixed parameter list, and Apache strips it before proxy_fcgi. The FOG installer emits the necessary web server configuration, but a server installed before this was fixed still has the old configuration on disk. If either method returns 401 Unauthorized with credentials you know are correct, re-run the installer to refresh the web server configuration. The fog-api-token / fog-user-token pair travels in its own headers, is unaffected, and needs no reinstall — so it is also the quickest way to tell this problem apart from a genuinely bad credential.

Example

While many different tools can be used to make API calls, curl is one of the most basic ones if you are on Linux and want to give it a try:

curl -H 'Authorization: Bearer yourusertoken' \
     -X GET http://fogserver/fog/system/info

The same call using the token pair:

curl -H 'fog-api-token: yourapitoken' \
     -H 'fog-user-token: yourusertoken' \
     -X GET http://fogserver/fog/system/info

Routes and Methods

To keep the information in the documentation as universal as possible, we only show the URL for each API call.

GET

Here are some core GET calls:

Route	Description
/fog/system/info	Health check — confirms the API is enabled and reachable. Requires no token and returns a small JSON payload containing the server version.
/fog/task/active	Returns a list of pending and active tasks.
/fog/multicastsession/current	Returns a list of active multicast sessions.
/fog/host	Returns a list of all the registered hosts.
/fog/<class>/search/<term>	Returns the records of <class> whose name contains the term (hosts also match on MAC address, storage nodes on node hostname, settings on value), e.g. /fog/host/search/<term> for hosts or /fog/image/search/<term> for images. The term is matched literally: % and _ are not wildcards. A whole-number term also matches the id exactly.
/fog/unisearch?q=<term>&limit=<n>	Searches every class at once and returns the matches grouped by class, each as id and name. limit caps the rows per class, not overall; omit it or pass 0 for no cap. Within a class, names that start with the term sort first. Both fields may be sent as POST body fields instead. Also reachable as /fog/search?q=. This is what the sidebar search box in the web UI calls.
/fog/unisearch/<term>/<n>	The older path form of the call above. A term containing /, ?, # or % cannot travel in a path segment, so prefer ?q=.

POST

Creating an image

Use the following API call to create an image: /fog/image/create. You need to pass the following parameters:

Parameter	Description
name	The name of the image.
path	The path to the image.
imageTypeID	How the image is stored (see the table below).
osID	The operating system ID for the image.

Any other Image field (for example description, imagePartitionTypeID, format, or compress) may also be included in the body.

Image types — the value to pass as imageTypeID:

imageTypeID	Type
1	Single Disk - Resizable
2	Multiple Partition Image - Single Disk (Not Resizable)
3	Multiple Partition Image - All Disks (Not Resizable)
4	Raw Image (Sector By Sector, DD, Slow)

A successful create returns the full JSON of the saved image object.

Creating a task (deploy, capture, etc.)

Put the ID of the host in the URL of the API call: /fog/host/<id>/task (this also works for other tasking objects, such as groups). The body selects the task with a taskTypeID key, for example:

{"taskTypeID": "1"}

taskTypeID 1 deploys and 2 captures. The full list of task types follows.

The body key is taskTypeID, not taskType

The endpoint reads the JSON property taskTypeID. A body of {"taskType": "1"} leaves taskTypeID unset and results in a 404.

Task types — the value to pass as taskTypeID:

taskTypeID	Task
1	Deploy
2	Capture
3	Debug
4	Memtest86+
5	Test Disk
6	Disk Surface Test
7	Recover
8	Multi-Cast
10	Hardware Inventory
11	Password Reset
12	All Snapins
13	Single Snapin
14	Wake-Up
15	Deploy - Debug
16	Capture - Debug
17	Deploy - No Snapins
18	Fast Wipe
19	Normal Wipe
20	Full Wipe

The IDs are not contiguous

There is intentionally no task type 9, and 8 is Multi-Cast — pass the ID from the table, not the row position.

21 and 22 no longer exist

They were the two virus-scan types, and the 1.6 upgrade deletes them — queueing either now fails. See The virus scan is gone in 1.6.

Assign an image first

You must assign an image to the host (and the image must be enabled) before you can deploy it. Assign it with a PUT request (see below).

A successful task call returns an empty string ("").

PUT

Edit a host: /fog/host/<id>/edit. Example body:

{"imageID": "1"}

A successful edit returns the full JSON of the updated host object.

Pagination, expansion & plugin items

FOG 1.6 adds opt-in query features for working with the API: paging large list results, inlining related objects with ?expand=…, and reading plugin-injected associations from the pluginItems envelope. See API Pagination, Expansion & Plugin Items.