API Documentation

Introduction

Welcome to the faithed API documentation. Our RESTful API allows developers to build applications that interact with the faithed platform.

Base URL

https://faithed.app/api

Content Type

All requests and responses use JSON format.

Content-Type: application/json

Note: All API requests must be made over HTTPS. HTTP requests will be rejected.

Authentication

The faithed API uses JWT (JSON Web Tokens) for authentication. Include your token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Obtaining a Token

Use the login endpoint to obtain a JWT token. The token is valid for 30 days.

Security: Never share your JWT token. Store it securely and never commit it to version control.

Authentication Endpoints

Register New User

POST /auth/register

Create a new user account.

Request Body

Parameter	Type	Required	Description
`email`	string	Yes	User's email address
`username`	string	Yes	Unique username (3-20 chars)
`password`	string	Yes	Password (min 8 chars)
`displayName`	string	No	Display name
`dateOfBirth`	string	Yes	Date of birth (YYYY-MM-DD)
`inviteCode`	string	No	Invite code from referrer

Example Request

{
  "email": "[email protected]",
  "username": "john_believer",
  "password": "SecurePass123!",
  "displayName": "John Smith",
  "dateOfBirth": "1990-05-15",
  "inviteCode": "FAITH-SARAH-ABC123"
}

Response

200 OK

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_abc123",
    "email": "[email protected]",
    "username": "john_believer",
    "displayName": "John Smith",
    "createdAt": "2026-02-04T10:30:00Z"
  }
}

Login

POST /auth/login

Authenticate and receive a JWT token.

Request Body

Parameter	Type	Required	Description
`email`	string	Yes	User's email address
`password`	string	Yes	User's password
`remember`	boolean	No	Extended session (default: false)

Example Request

{
  "email": "[email protected]",
  "password": "SecurePass123!",
  "remember": true
}

Response

200 OK

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_abc123",
    "email": "[email protected]",
    "username": "john_believer",
    "displayName": "John Smith",
    "avatar": "https://faithed.app/avatars/user_abc123.jpg",
    "isPremium": false
  }
}

Check Username Availability

POST /auth/check-username

Check if a username is available.

Request Body

{
  "username": "john_believer"
}

Response

{
  "available": true
}

Post Endpoints

Create Scrip (Text Post)

POST /posts/scrip

Create a short text post (max 500 characters).

Headers

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Request Body

{
  "content": "Blessed is the one who trusts in the Lord! #FaithOverFear",
  "tags": ["FaithOverFear", "Trust"],
  "mentions": ["@sarahj"],
  "visibility": "public"
}

Response

201 Created

{
  "success": true,
  "post": {
    "id": "post_xyz789",
    "type": "scrip",
    "content": "Blessed is the one who trusts in the Lord! #FaithOverFear",
    "author": {
      "id": "user_abc123",
      "username": "john_believer",
      "displayName": "John Smith",
      "avatar": "https://faithed.app/avatars/user_abc123.jpg"
    },
    "createdAt": "2026-02-04T14:30:00Z",
    "sparks": {
      "blessing": { "like": 0, "love": 0, "leader": 0 },
      "breakthrough": { "light": 0, "gem": 0, "gold": 0 }
    }
  }
}

Create Scroll (Long-Form Post)

POST /posts/scroll

Create a long-form text post (no character limit).

Request Body

{
  "title": "My Journey to Faith",
  "content": "Long form content here...",
  "coverImage": "https://...",
  "tags": ["Testimony", "Faith"],
  "visibility": "public"
}

Create Shot (Photo Post)

POST /posts/shot

Create a photo post.

Request Body (multipart/form-data)

images: [File, File, ...]  // Max 10 images
caption: "Beautiful sunset worship"
tags: ["Worship", "Nature"]

Get Feed

GET /posts/feed

Get personalized feed of posts.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Posts per page (default: 20, max: 100)
`type`	string	Filter by type: scrip, scroll, shot, sermon, scenery

Response

200 OK

{
  "success": true,
  "posts": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 487,
    "hasMore": true
  }
}

Spark Endpoints

Send Spark

POST /sparks/send

React to a post with a Spark.

Request Body

{
  "postId": "post_xyz789",
  "sparkType": "blessing-love"
}

Valid Spark Types:

blessing-like, blessing-love, blessing-leader
breakthrough-light, breakthrough-gem, breakthrough-gold

Response

200 OK

{
  "success": true,
  "spark": {
    "id": "spark_def456",
    "postId": "post_xyz789",
    "type": "blessing-love",
    "points": 2,
    "createdAt": "2026-02-04T14:35:00Z"
  }
}

Seed Endpoints

Send Seeds

POST /seeds/send

Send Seeds to support a post or user. (Premium only)

Request Body

{
  "postId": "post_xyz789",
  "amount": 10,
  "message": "Great message!"
}

Response

200 OK

{
  "success": true,
  "transaction": {
    "id": "txn_ghi012",
    "amount": 10,
    "from": "user_abc123",
    "to": "user_def456",
    "postId": "post_xyz789",
    "createdAt": "2026-02-04T14:40:00Z"
  },
  "newBalance": 990
}

Messaging Endpoints

Get Conversations

GET /messages/conversations

Get list of message conversations.

Response

200 OK

{
  "success": true,
  "conversations": [
    {
      "id": "conv_jkl345",
      "participants": [...],
      "lastMessage": {
        "content": "See you at church!",
        "sentAt": "2026-02-04T13:20:00Z"
      },
      "unreadCount": 2
    }
  ]
}

Send Message

POST /messages/send

Send a direct message.

Request Body

{
  "conversationId": "conv_jkl345",
  "content": "Hello friend!"
}

Prayer Request Endpoints

Create Prayer Request

POST /prayers

Create a new prayer request.

Request Body

{
  "title": "Healing for my mother",
  "description": "Please pray for my mother's recovery...",
  "category": "healing",
  "visibility": "public",
  "anonymous": false
}

Response

201 Created

{
  "success": true,
  "prayer": {
    "id": "prayer_mno678",
    "title": "Healing for my mother",
    "description": "Please pray for my mother's recovery...",
    "author": {...},
    "prayerCount": 0,
    "status": "active",
    "createdAt": "2026-02-04T15:00:00Z"
  }
}

Marketplace Endpoints

Create Listing

POST /marketplace/listings

Create a marketplace listing.

Request Body

{
  "title": "Study Bible - NIV",
  "description": "Like new condition...",
  "category": "books",
  "price": 25.00,
  "currency": "USD",
  "images": ["https://..."],
  "condition": "like-new",
  "shippingAvailable": true
}

Opportunity Endpoints

Post Opportunity

POST /opportunities

Post a job or business opportunity.

Request Body

{
  "type": "job",
  "title": "Youth Pastor",
  "organization": "Grace Community Church",
  "description": "Full-time position...",
  "location": "Austin, TX",
  "salary": "50000-60000",
  "remote": false
}

SwapSpace Endpoints

Create Swap Listing

POST /swaps

Create a housing, job, or workspace swap listing.

Request Body

{
  "type": "housing",
  "title": "2BR Apartment in NYC",
  "location": "New York, NY",
  "duration": "3 months",
  "seeking": "Housing in Los Angeles",
  "dates": {
    "start": "2026-06-01",
    "end": "2026-08-31"
  },
  "verified": true
}

Advertising Endpoints

Create ReachOut Campaign

POST /reachout/campaigns

Create a new ReachOut campaign.

Request Body

{
  "name": "Summer Camp Registration",
  "objective": "conversions",
  "budget": 500.00,
  "duration": 30,
  "targeting": {
    "ageRange": [13, 18],
    "denominations": ["Baptist", "Methodist"],
    "interests": ["Youth Ministry", "Camps"]
  },
  "creative": {
    "image": "https://...",
    "headline": "Join our summer camp!",
    "description": "Amazing experience...",
    "cta": "Register Now"
  }
}

Error Codes

Code	Status	Description
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred

Error Response Format

400 Bad Request

{
  "success": false,
  "error": "Invalid request body",
  "code": "INVALID_REQUEST",
  "details": {
    "field": "email",
    "message": "Email is required"
  }
}

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability.

Standard Limits

Endpoint Category	Limit	Window
Authentication	10 requests	15 minutes
Read Operations (GET)	300 requests	15 minutes
Write Operations (POST/PUT)	100 requests	15 minutes
File Uploads	20 requests	15 minutes

Premium Limits

Premium users receive higher rate limits:

Read Operations: 1,000 requests / 15 minutes
Write Operations: 500 requests / 15 minutes
File Uploads: 100 requests / 15 minutes

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1675523400

Important: When you exceed rate limits, you'll receive a 429 status code. Wait until the reset time before making more requests.