Faithfully API Documentation

Quick Start

Get up and running in three steps.

1

Get your API key

Open the Faithfully app, go to Settings > API Access, and generate your API key. Keys start with fai_.

2

Set the authorization header

Include your key in every request using the X-API-Key header.

Header

X-API-Key: fai_your_api_key_here

3

Make your first request

Fetch your profile to verify everything works.

curl

curl -X GET https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/me \
  -H "X-API-Key: fai_your_api_key_here"

Authentication

All API requests require a valid API key.

API Key Format

Keys are prefixed with fai_ followed by a unique token. Manage your keys in the Faithfully app under Settings > API Access.

Example Request

curl https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/me \
  -H "X-API-Key: fai_abc123def456"

⚠

Keep your key secret. Do not share your API key or commit it to version control. If compromised, revoke it immediately in app settings and generate a new one.

Rate Limits

Tier	Requests / Hour	Requests / Day
Pro	100	1,000
Business	1,000	10,000
Enterprise	Unlimited	Unlimited

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoints Reference

Base URL: https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi

GET /v1/agreements List your agreements

Query Parameters

limit integer optional Max results per page (default: 20, max: 100)

offset integer optional Number of results to skip for pagination

status string optional Filter by status: pending, active, completed, cancelled

type string optional Filter by agreement type

Example

curl

curl -X GET "https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements?limit=10&status=active" \
  -H "X-API-Key: fai_your_key"

JavaScript

const response = await fetch(
  'https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements?limit=10&status=active',
  {
    headers: { 'X-API-Key': 'fai_your_key' }
  }
);
const data = await response.json();
console.log(data.agreements);

Python

import requests

response = requests.get(
    'https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements',
    headers={'X-API-Key': 'fai_your_key'},
    params={'limit': 10, 'status': 'active'}
)
data = response.json()
print(data['agreements'])

Response

JSON

{
  "agreements": [
    {
      "id": "abc123",
      "agreement_type": "loan",
      "title": "Personal Loan Agreement",
      "status": "active",
      "user_a": "user_id_1",
      "user_b": "user_id_2",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

POST /v1/agreements Create a new agreement

Request Body

agreement_type string required One of: loan, lease, item_borrow, service, shared_expense, promissory_note

title string required Title of the agreement

counterparty_email string required Email address of the other party

terms object required Type-specific terms (see Agreement Types)

Example

curl

curl -X POST https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements \
  -H "X-API-Key: fai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agreement_type": "loan",
    "title": "Personal Loan to Jane",
    "counterparty_email": "jane@example.com",
    "terms": {
      "principal_amount": 5000,
      "interest_rate": 5.0,
      "duration_months": 12,
      "payment_frequency": "monthly"
    }
  }'

JavaScript

const response = await fetch(
  'https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'fai_your_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agreement_type: 'loan',
      title: 'Personal Loan to Jane',
      counterparty_email: 'jane@example.com',
      terms: {
        principal_amount: 5000,
        interest_rate: 5.0,
        duration_months: 12,
        payment_frequency: 'monthly'
      }
    })
  }
);
const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    'https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements',
    headers={
        'X-API-Key': 'fai_your_key',
        'Content-Type': 'application/json'
    },
    json={
        'agreement_type': 'loan',
        'title': 'Personal Loan to Jane',
        'counterparty_email': 'jane@example.com',
        'terms': {
            'principal_amount': 5000,
            'interest_rate': 5.0,
            'duration_months': 12,
            'payment_frequency': 'monthly'
        }
    }
)
data = response.json()
print(data)

Response

JSON

{
  "id": "new_agreement_id",
  "agreement_type": "loan",
  "title": "Personal Loan to Jane",
  "status": "draft",
  "counterparty_email": "jane@example.com",
  "terms": {
    "principal_amount": 5000,
    "interest_rate": 5.0,
    "duration_months": 12,
    "payment_frequency": "monthly"
  },
  "created_at": "2026-02-24T15:00:00Z"
}

GET /v1/agreements/:id Get agreement details

Path Parameters

id string required The agreement ID

Example

curl

curl -X GET https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements/abc123 \
  -H "X-API-Key: fai_your_key"

Response

JSON

{
  "id": "abc123",
  "agreement_type": "loan",
  "title": "Personal Loan to Jane",
  "status": "active",
  "user_a": "lender_user_id",
  "user_b": "borrower_user_id",
  "terms": {
    "principal_amount": 5000,
    "interest_rate": 5.0,
    "duration_months": 12,
    "payment_frequency": "monthly"
  },
  "balance": {
    "principal_remaining": 3500,
    "total_paid": 1500,
    "next_payment_date": "2026-03-01"
  },
  "created_at": "2026-01-15T10:30:00Z",
  "activated_at": "2026-01-16T08:00:00Z"
}

POST /v1/agreements/:id/send Send agreement for review

Description

Sends the agreement to the counterparty for review and signature. The agreement must be in draft status. An invitation email will be sent to the counterparty.

Path Parameters

id string required The agreement ID

Example

curl

curl -X POST https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/agreements/abc123/send \
  -H "X-API-Key: fai_your_key"

Response

JSON

{
  "success": true,
  "message": "Agreement sent for review",
  "agreement_id": "abc123",
  "status": "pending"
}

GET /v1/me Get current user profile

Description

Returns the authenticated user's profile information. Useful for verifying API key validity and retrieving account details.

Example

curl

curl -X GET https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/me \
  -H "X-API-Key: fai_your_key"

Response

JSON

{
  "id": "user_id",
  "email": "you@example.com",
  "display_name": "John Doe",
  "subscription_tier": "pro",
  "stripe_connected": true,
  "created_at": "2025-06-01T12:00:00Z"
}

GET /v1/stripe/status Check Stripe Connect status

Description

Returns the status of the user's Stripe Connect account. A connected Stripe account is required to send or receive payments through agreements.

Example

curl

curl -X GET https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/stripe/status \
  -H "X-API-Key: fai_your_key"

Response

JSON

{
  "connected": true,
  "payouts_enabled": true,
  "charges_enabled": true,
  "account_id": "acct_..."
}

POST /v1/stripe/setup Set up Stripe Connect

Description

Initiates the Stripe Connect onboarding flow. Returns a URL that the user should visit to complete Stripe account setup.

Example

curl

curl -X POST https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/stripe/setup \
  -H "X-API-Key: fai_your_key"

Response

JSON

{
  "url": "https://connect.stripe.com/setup/...",
  "expires_at": "2026-02-24T16:00:00Z"
}

GET /v1/openapi.json Get OpenAPI specification

Description

Returns the full OpenAPI 3.1 specification for the Faithfully API. Use this to auto-generate client libraries, import into Postman, or configure ChatGPT Actions and Claude MCP.

Example

curl

curl -X GET https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/openapi.json

ⓘ

The OpenAPI spec is publicly accessible and does not require authentication.

Agreement Types

Faithfully supports 8 agreement types across personal agreements and fidelity contracts.

Personal Agreements

💰

Loan

loan

Personal loans with interest, scheduled payments, and full amortization tracking.

Required: principal_amount, interest_rate, duration_months, payment_frequency

🏠

Lease

lease

Residential or commercial lease agreements with rent tracking and security deposits.

Required: monthly_rent, security_deposit, lease_start_date, lease_end_date

📦

Item Borrow

item_borrow

Lend or borrow items with optional rental fees, due dates, and damage deposit tracking.

Required: item_name, item_value, return_date

🛠

Service

service

Service contracts for freelance work, consulting, or recurring services with flexible payment schedules.

Required: service_description, payment_amount, payment_type, schedule_type

💲

Shared Expense

shared_expense

Split costs between parties with equal, percentage, or fixed-amount splits.

Required: total_amount, split_type, expense_description

📜

Promissory Note

promissory_note

Formal promise to pay a specified sum, with lump sum or installment options.

Required: principal_amount, interest_rate, payment_type, maturity_date

Fidelity Contracts

💍

Long-Term Relationship

fidelity_ltr

Fidelity agreements for long-term committed relationships with customizable terms and penalties.

Required: partner_email, contract_terms, penalty_amount

💓

Short-Term Relationship

fidelity_str

Fidelity agreements for shorter-term relationships with defined boundaries and accountability.

Required: partner_email, contract_terms, duration

ChatGPT Actions Guide

Integrate Faithfully into a custom GPT using Actions.

Open your GPT settings

Go to ChatGPT > My GPTs > Create/Edit GPT and navigate to the Configure tab.

Add a new Action

Scroll down to Actions and click Create new action.

Import the OpenAPI spec

Click Import from URL and paste the following URL:

URL

https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/openapi.json

Configure authentication

Set the authentication type to API Key, header name to X-API-Key, and enter your fai_ key.

Test it out

Save the GPT and try asking it to "list my agreements" or "create a new loan agreement."

Claude MCP Integration

Connect Faithfully to Claude using the Model Context Protocol.

MCP Server Configuration

Add the following to your Claude MCP configuration file:

JSON

{
  "mcpServers": {
    "faithfully": {
      "type": "openapi",
      "url": "https://us-central1-faithfully-app.cloudfunctions.net/faithfullyApi/v1/openapi.json",
      "headers": {
        "X-API-Key": "fai_your_api_key_here"
      }
    }
  }
}

Available Tools

Once connected, Claude can use the following tools:

Tool	Description
`listAgreements`	List and filter your agreements
`createAgreement`	Create a new agreement of any type
`getAgreement`	Get full details of a specific agreement
`sendAgreement`	Send an agreement for counterparty review
`getProfile`	Get your account profile and subscription info
`checkStripeStatus`	Check if Stripe Connect is set up
`setupStripe`	Start the Stripe Connect onboarding flow

Example Usage

Once configured, you can ask Claude things like:

Prompt

"Create a loan agreement for $2,000 with 3% interest over 6 months
to jane@example.com and send it for review."

Pricing

API access is free for all users. Create agreements from ChatGPT, Claude, Gemini, or any AI assistant at no cost.

Free

$0

Create agreements
API access (50 req/day)
ChatGPT, Claude & Gemini integration
Payment tracking

Get Started Free

Pro

$9.99/mo

Everything in Free
In-app AI Assistant
500 req/day
Priority support

Upgrade to Pro

Business

$29.99/mo

Everything in Pro
5,000 req/day
Bulk operations
Dedicated support

Go Business

ⓘ

How Faithfully makes money: A 1% platform fee (minimum $1) is applied to each payment processed through an agreement. Creating and signing agreements is always free. This keeps API access free for everyone while Faithfully earns revenue as agreements are used.

SDKs & Libraries

Official client libraries for the Faithfully API.

📜

Node.js / npm

@faithfully/sdk

Coming Soon

🐍

Python / pip

faithfully-sdk

Coming Soon

⚡

Go

go-faithfully

Coming Soon

💎

Ruby / gem

faithfully

Coming Soon

ⓘ

In the meantime, you can use the OpenAPI spec to auto-generate a client in any language using tools like openapi-generator.

API

Quick Start

Get your API key

Set the authorization header

Make your first request

Authentication

API Key Format

Rate Limits

Endpoints Reference

Query Parameters

Example

Response

Request Body

Example

Response

Path Parameters

Example

Response

Description

Path Parameters

Example

Response

Description

Example

Response

Description

Example

Response

Description

Example

Response

Description

Example

Agreement Types

Personal Agreements

Loan

Lease

Item Borrow

Service

Shared Expense

Promissory Note

Fidelity Contracts

Long-Term Relationship

Short-Term Relationship

ChatGPT Actions Guide

Open your GPT settings

Add a new Action

Import the OpenAPI spec

Configure authentication

Test it out

Claude MCP Integration

MCP Server Configuration

Available Tools

Example Usage

Pricing

SDKs & Libraries

Node.js / npm

Python / pip

Go

Ruby / gem

Download Faithfully