Skip to main content
Welcome to the Formal API! You can use our API to access Formal API endpoints.

​
Base URL

​
Formal client libraries

​
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 console. 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. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Formal’s servers.

​
HTTP

Formal API HTTP error codes:

​
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 returns 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.