Base URL
Formal client libraries
- Go: Go-SDK
Overview
Formal API is built using gRPC, a highly performant and open source universal Remote Procedure Call (RPC) framework. gRPC requires inputs and outputs to be formatted as protocol buffers (protobufs), Google’s mature open source mechanism for serializing structured data. To leverage gRPC, Formal implements a protocol-buffer-based API. gRPC ensures that both the client and server agree on the same data structures and interfaces. For more information about gRPC, see the official gRPC documentation.Authentication
The Formal API uses API keys to authenticate requests. You can view and manage your API keys in the Formal Dashboard. Keep your API keys secure! Do not share your secret API keys in publicly accessible areas like GitHub, Google Drive, and so forth. To authenticate use-H x-api-key: {your_api_key} in your curl command
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Errors
In general: Codes in the 2xx range indicate success. Code in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate error with Formal’s servers.HTTP
Formal API HTTP error codes:| Code | HTTP Status | Meaning |
|---|---|---|
| invalid_argument | 400 Bad Request | Request is invalid, regardless of system state. |
| out_of_range | 400 Bad Request | The operation was attempted past the valid range. |
| unauthenticated | 401 Unauthorized | Caller doesn’t have valid authentication credentials for the operation. |
| permission_denied | 403 Forbidden | Caller isn’t authorized to perform the operation. |
| not_found | 404 Not Found | User requested a resource (for example, a file or directory) that can’t be found. |
| unimplemented | 404 Not Found | The operation isn’t implemented, supported, or enabled. |
| canceled | 408 Request Timeout | RPC canceled, usually by the caller. |
| deadline_exceeded | 408 Request Timeout | Deadline expired before RPC could complete or before the client received the response. |
| already_exists | 409 Conflict | Caller attempted to create a resource that already exists. |
| aborted | 409 Conflict | The operation was aborted, often because of concurrency issues like a database transaction abort. |
| failed_precondition | 412 Precondition Failed | Operation can’t be completed because the system isn’t in the required state. |
| resource_exhausted | 429 Too Many Requests | Operation can’t be completed because some resource is exhausted. |
| unsupported_protocol | 464 Unsupported Protocol | The API requires HTTP/2. Requests using HTTP/1.1 or other protocols will receive this error. |
| internal | 500 Internal Server Error | An invariant expected by the underlying system has been broken. Reserved for serious errors. |
| unknown | 500 Internal Server Error | Catch-all for errors of unclear origin and errors without a more appropriate code. |
| data_loss | 500 Internal Server Error | Unrecoverable data loss or corruption. |
| unavailable | 503 Service Unavailable | The service is currently unavailable, usually transiently. Clients should back off and retry. |
Pagination
All top-level API resources have support for bulk fetches through “list” API methods. These list API methods share a common structure and accept, at a minimum, the following parameters:limit, cursor, and order.
Formal’s list API methods use cursor-based pagination through the cursor parameter. The parameter accepts an existing object ID value and return objects in specified chronological order.
Parameters
- limit (integer, required): Specifies a limit on the number of objects to return, ranging between 1 and 100.
- cursor (string): A cursor to use in pagination.
- order (string, default: “asc”): Specifies in which chronological order the list should be sorted. Potential values:
ASC,DESC
List Response Format
- count (integer, required): Number of objects returned.
- next_cursor (string, required): Next cursor in the list.