FileMaker Cloud 17 Admin API Guide
About the FileMaker Admin API
Overview
The FileMaker® Admin API is an application programming interface (API) that allows web services to perform administrative tasks on FileMaker Cloud. Because this API conforms to Representational State Transfer (REST) architecture, the FileMaker Admin API is a REST API.
Your web service or application calls the FileMaker Admin API to obtain an authentication token for access to a FileMaker Cloud instance. After authentication, your code can use FileMaker Admin API methods to perform database and schedule-related tasks.
The FileMaker Admin API returns data in JavaScript Object Notation (JSON), a text format that is commonly used with REST APIs because JSON is independent of specific programming language formats.
This guide assumes you are experienced with:
- using FileMaker Pro Advanced to upload databases. See FileMaker Pro Advanced Help.
- using FileMaker Cloud to host and manage databases. See FileMaker Cloud Help.
- using REST APIs in server-side applications or web services that call POST, GET, PUT, and DELETE methods with data in JSON format. You can use any programming languages or tools you choose.
To use the FileMaker Admin API, follow these steps:
- Accept the FileMaker Admin API Trial License Agreement when you first sign in to FileMaker Cloud 1.17.0.
- Write code that calls FileMaker Admin API methods to perform administrative tasks for a FileMaker Cloud instance.
- Optionally, write code that calls FileMaker Data API methods to work with records in hosted databases. See FileMaker Data API Guide.
- Test that FileMaker Admin API access is working correctly.
- Monitor your results by reviewing the gateway.log file, where all API calls are logged. Check this log for error information. See Status and error codes for a description of HTTP and FileMaker error codes returned.
How a FileMaker Admin API call is processed
- A REST API client sends a FileMaker Admin API call (an HTTPS request) to the Apache HTTP server used by FileMaker Cloud as an access point.
- The Apache server routes the request to the FileMaker Cloud web server. The FileMaker Admin API engine on that web server converts the HTTPS request (URL and JSON data) into a format compatible with the FileMaker Database Server.
- The FileMaker Server Helper helps manage the FileMaker Database Server, and communicates the request to the Database Server.
- The Database Server sends results of the request back to the FileMaker Cloud web server.
- The FileMaker Admin API on the web server converts the results into an HTTPS response (URL with JSON data) and passes the response back to the Apache server.
- The Apache server sends the HTTPS response to the requesting REST API client.
FileMaker Admin API calls
FileMaker Admin API features
The FileMaker Admin API provides a REST API that you can use to automate some routine administrative tasks through scripting instead of FileMaker Cloud Admin Console.
The FileMaker Admin API allows your code to:
- log in to or log out of a FileMaker Cloud instance. See Calls that connect to or disconnect from FileMaker Cloud.
- list, open, pause, resume, and close databases hosted on that instance. See Calls that access FileMaker databases.
- disconnect and send messages to database clients. See Calls that disconnect or send a message to clients.
- list schedules; create a message schedule; create a FileMaker script schedule; edit, duplicate, delete, run, and enable or disable a schedule. See Calls that manage FileMaker script schedules.
The FileMaker Admin API is stateful, keeping track of the state of interactions. Start with a login call to the FileMaker Cloud instance, which returns the session token. Subsequent calls must also pass the token. The token is valid either until you log out of a solution or for 15 minutes after the last call that specified the token. (While the token is valid, each call that specifies the token resets the session timeout counter to zero.)
These API calls are synchronous and wait for a response from FileMaker Cloud: login, logout, send message, list databases, and get schedules; create, edit, duplicate, run, enable or disable, and delete a message or FileMaker script schedule. These API calls are asynchronous and do not wait for a response from FileMaker Cloud: open, pause, resume, and close databases; and disconnect clients. You may want to follow an asynchronous call with a list or get call to confirm the file status has changed. For example, follow a close database call with a list databases call to confirm the database is closed.
Admin API call components
The FileMaker Admin API calls consist of the following components.
| Component | Description |
|---|---|
An HTTP method (also known as an HTTP verb) |
The FileMaker Admin API uses the following HTTP methods:
|
An HTTP header |
FileMaker Admin API calls use these headers:
|
| A call URL | FileMaker Admin API URLs all start with: /admin/api/v1 |
| Parameter data in JSON format | Used with: login; open and close database; disconnect and send message to clients; create message or FileMaker script schedule; edit schedule. |
Calls that connect to or disconnect from FileMaker Cloud
Log in to FileMaker Cloud
To log in, use the HTTP POST method with the user/login URL. Only the root administrator can log in using the FileMaker Admin API. If the account name and password are authenticated, your code receives an access token that defines your connection to FileMaker Cloud.
| HTTP method | POST |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json |
| Parameters | User name and password to log in. Both are strings. For example: { |
| Response | A result code of 0 and the access token. For example: { |
Log out of FileMaker Cloud
To log out, use the HTTP POST method with the user/logout URL. Use the access token returned during login in the Logout header.
| HTTP method | POST |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | A result code of 0. For example: { |
Calls that access FileMaker databases
To open, pause, resume, or close a database, you must know the database ID. Use the list databases API call to get information for all hosted databases, including database IDs.
List databases
To list databases, use the HTTP GET method with the databases URL. Listing the hosted databases returns three sets of data: files, clients, and connection counts.
| HTTP method | GET |
|---|---|
| URL |
|
| HTTP header | Authorization: Bearer token |
| Parameters | None |
| Response | For each set of data (files, clients, and connection counts), a set of results and a result code of 0. Connection counts are:
For example: { |
Open a database
To open a database, use the HTTP PUT method with the :db_id/open URL. Use the list databases call to get the database ID to include in the URL. To open all databases, set db_id in the URL equal to 0.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | Optional: The key parameter, a string, specifies a previously created encryption key that opens the database on FileMaker Cloud. Note:FileMaker Admin API does not validate the encryption key. You receive a result code of 0 even if you enter an invalid key. For example: { |
| Response | A result code of 0. For example: { |
Pause a database
To pause a database, use the HTTP PUT method with the :db_id/pause URL. Use the list databases call to get the database ID to include in the URL.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | A result code of 0. For example: { |
Resume a database
To resume a database, use the HTTP PUT method with the :db_id/resume URL. Use the list databases call to get the database ID to include in the URL.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | A result code of 0. For example: { |
Close a database
To close a database, use the HTTP PUT method with the :db_id/close URL. Use the list databases call to get the database ID to include in the URL. To close all databases, set db_id in the URL equal to 0. If no clients are connected, databases are closed immediately. If clients are connected, databases are closed in 90 seconds.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | Optional: Enter a text string to send a message to connected clients. { |
| Response | A result code of 0. For example: { |
Calls that disconnect or send a message to clients
To disconnect or send a message to a FileMaker client, you must know the client ID. Use the list databases API call to get client IDs.
Disconnect clients
To disconnect clients, use the HTTP PUT method with the clients/:client_id/disconnect URL. To disconnect all clients, set client_id in the URL equal to 0.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | Optionally, specify:
{ |
| Response | For example: { |
Send a message to clients
To send a message to one or more clients, use the HTTP POST method with the :client_id/message URL. To send a message to all clients, set client_id in the URL equal to 0.
| HTTP method | POST |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | Enter a text string to send as a message to connected clients. Range: 0 to 200 characters. { |
| Response | A result code of 0. For example: { |
Notes
- Errors for this API call are not logged in the gateway.log file.
- When you send a message to clients, FileMaker Admin API does not validate the client ID. You receive a result code of 0 even if you enter an incorrect or nonexisting client ID.
Calls that manage FileMaker script schedules
To edit, duplicate, delete, run, and enable or disable a schedule, you must know the schedule ID. Use the get schedules API call to get information for schedules, including schedule IDs.
Notes
- When you create, edit, duplicate, delete, run, and enable or disable a schedule, the JSON results return the schedule parameters along with the result code of 0.
- When you create, edit, duplicate, delete, run, or enable or disable a schedule, the JSON results return a status code for the schedule: 1 if the schedule is idle, or 2 if the schedule is running. In addition,
lastErrorprovides the error code for the last run if the script has previously run. - When you create or edit a schedule, or get a list of FileMaker script schedules, and have set
freqTypeto 1 (run once), the results include unrelated repeat settings such asrepeatFrequency,repeatInterval,endDate,daysOfTheWeek, andrepeatTask. - FileMaker Cloud doesn't support sending email in FileMaker script schedules.
- When you create a schedule and omit more than one required parameter, only the first missing parameter is logged.
- All times are calculated based on 24-hour UTC time (Coordinated Universal Time), which is used by FileMaker Cloud. You must enter all dates in this format, using hyphens: yyyy-mm-dd-hh-mm-ss.
- For all dates returned, seconds are rounded to 0.
Get schedules
To get a list of FileMaker script schedules, use the HTTP GET method with the schedules or schedules/:schedule_id URL. An error result is returned if you specify a schedule ID that doesn't exist.
| HTTP method | GET |
|---|---|
| URL |
|
| HTTP header | Authorization: Bearer token |
| Parameters | None |
| Response | A result code of 0 followed by the schedule settings. For example: { |
Create a message schedule
To create a message schedule, use the HTTP POST method with the schedules URL. You must specify the parameters required by the REST API.
| HTTP method | POST |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Required parameters | You must specify:
For example (all databases): { |
| Optional parameters | For Boolean parameters, false disables the parameter and true enables it. The default is false.
For example: { |
| Response | See Edit a schedule for an example. |
Create a FileMaker script schedule
To create a FileMaker script schedule, use the HTTP POST method with the schedules URL. You must specify the mandatory parameters required by the REST API.
| HTTP method | POST |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Required parameters | You must specify:
For example: { |
| Optional parameters | For Boolean parameters, false disables the parameter and true enables it. The default is false.
For example: { |
| Response | See Edit a schedule for an example. |
Edit a schedule
To edit a schedule, use the HTTP PUT method with the schedules/:schedule_id URL. When you edit a schedule, you must specify all parameters that are set as non-default. Any settings that are not specified in the JSON parameter list revert to their defaults.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | See Create a message schedule and Create a FileMaker script schedule for the parameters to specify when you edit a script. |
| Response | { |
Duplicate a schedule
To duplicate a schedule, use the HTTP POST method with the schedules/:schedule_id/dupicate URL. Use the get schedules API call to find the schedule ID after you duplicate a schedule.
| HTTP method | POST |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | See Edit a schedule for an example. |
Delete a schedule
To delete a schedule, use the HTTP DELETE method with the schedules/:schedule_id URL. Use the get schedules API call to verify the schedule's deletion.
| HTTP method | DELETE |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | See Edit a schedule for an example. |
Run a schedule
To run a schedule, use the HTTP PUT method with the schedules/:schedule_id/run URL. Use the run API call to manually run a schedule. Use the get schedules API call to verify the results.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | See Edit a schedule for an example. |
Enable a schedule
To enable a schedule, use the HTTP PUT method with the schedules/:schedule_id/enable URL. Enabling a schedule that runs in the past does not produce an error, but returns the enabled parameter as false.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | See Edit a schedule for an example. |
Disable a schedule
To disable a schedule, use the HTTP PUT method with the schedules/:schedule_id/disable URL. You can only disable schedules that will run in the future.
| HTTP method | PUT |
|---|---|
| URL |
|
| HTTP header | Content-Type: application/json Authorization: Bearer token |
| Parameters | None |
| Response | See Edit a schedule for an example. |
Status and error codes
When an error occurs, the FileMaker Admin API generally returns an HTTP 400-level status code with an error code in a JSON object.
| HTTP status code | HTTP category | JSON error format |
|---|---|---|
| 200 | Successful request | { |
| 400 | Bad parameter | {
Notes
|
| 401, 403, 4nn | Invalid session. For example, the session timed out, the user logged out, the user could not log in. |
|
| 477 | FileMaker Server error. | Includes FileMaker error messages and error codes. See FileMaker error codes. |
| 500-5nn | Usually caused by a connection to server error. |
For information about additional HTTP status codes returned, see www.w3.org.
FileMaker error codes
Note:If you omit or misspell the header Content-Type for a FileMaker Cloud Admin API call, you will receive the 958 result code.
| FileMaker error code | Description |
|---|---|
| 3 | Unavailable command in current state |
| 4 | Command is unknown |
| 8 | Empty result |
| 9 | Insufficient privileges |
| 212 | The provided account name and password cannot be used to access this file. |
| 802 | Unable to open the file |
| 958 | Parameter missing |
| 960 | Parameter is invalid |
| 10006 | Service already running |
| 10600 | Schedule is missing Schedule at specified index no longer exists |
| 10601 | Schedule is misconfigured; invalid taskType or run status |
| 10603 | Schedule can't be created or duplicated |
| 10604 | Cannot enable schedule |
| 10610 | No schedules created in configuration file Note:No schedule is found with the specified parameter. |
| 10611 | Schedule name is already used |
| 10904 | No application files for this operation |
| 10906 | Script is missing |
| 10908 | System script aborted Note:The time limit was exceeded or the server stopped. |
| 11005 | Disconnect client invalid ID |
| 25004 | Parameters are invalid |
| 25006 | Invalid session error |
For a list of FileMaker Pro Advanced error codes, see FileMaker error codes in FileMaker Pro Advanced Help.
Use FileMaker Admin API calls
Communication with FileMaker Cloud
Use encryption for communication between your REST API application and FileMaker Cloud.
- The FileMaker Admin API requires your applications to use an HTTPS connection. HTTPS connections use Secure Sockets Layer (SSL) encryption for communication.
- A custom SSL certificate for FileMaker Cloud is required for production use.
- The language or technology that you use to call the FileMaker Admin API must support Transport Layer Security (TLS) v1.2 to communicate with FileMaker Cloud.