SDKs

Overview

Formal provides SDKs for programmatic access to the platform. Use SDKs to build custom tools, automation, and integrations.

For most infrastructure management tasks, use the Terraform provider instead of SDKs.

Official SDKs

The official Formal SDK for Go is available:

Go: github.com/formalco/go-sdk

Features

Create, read, update, delete Formal objects
Query logs and sessions programmatically
Manage policies dynamically
Integrate Formal into CI/CD pipelines
Build custom dashboards and reports

Go Example

Install the SDK:

go get github.com/formalco/go-sdk/v3@latest

List your Resources:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    formal "github.com/formalco/go-sdk/v3"
    corev1 "github.com/formalco/go-sdk/v3/core/v1"
)

func main() {
    client, err := formal.New(formal.WithAPIKey(os.Getenv("FORMAL_API_KEY")))
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.ResourceServiceClient.ListResources(context.Background(), &corev1.ListResourcesRequest{Limit: 50})
    if err != nil {
        log.Fatal(err)
    }

    for _, r := range res.Resources {
        fmt.Println(r.Id, r.Name, r.Technology)
    }
}

The client calls https://api.formal.ai by default.

HTTP API

You can also call the API directly. It uses the Connect protocol, not REST. Every method is a POST to https://api.formal.ai/<package>.<Service>/<Method> with a JSON body.

Authentication

export FORMAL_API_KEY="<YOUR_API_KEY>"

Example Requests

List Resources
Create User
Query Logs

curl -X POST "https://api.formal.ai/core.v1.ResourceService/ListResources" \
  -H "X-API-KEY: $FORMAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

curl -X POST "https://api.formal.ai/core.v1.UserService/CreateUser" \
  -H "X-API-KEY: $FORMAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "human",
    "human": {
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "alice@example.com"
    }
  }'

# Logs for alice@example.com over the last 24 hours (Unix seconds)
curl -X POST "https://api.formal.ai/core.v1.LogsService/ListLogsV2" \
  -H "X-API-KEY: $FORMAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"query\": \"user.formal.user.email:alice@example.com\",
    \"start_timestamp\": \"$(( $(date +%s) - 86400 ))\",
    \"end_timestamp\": \"$(date +%s)\",
    \"limit\": 50
  }"

The API requires HTTP/2. curl negotiates it automatically over HTTPS. HTTP/1.1-only clients receive a 464 error.

API Documentation

See the API Reference for complete endpoint documentation.

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Overview

Official SDKs

Features

Go Example

HTTP API

Authentication

Example Requests

API Documentation

​Overview

​Official SDKs

​Features

​Go Example

​HTTP API

​Authentication

​Example Requests

​API Documentation

Overview

Official SDKs

Features

Go Example

HTTP API

Authentication

Example Requests

API Documentation