API Documentation | FANN Developer

Authentication

All FANN API requests require authentication via a Bearer token. Tokens are scoped (read, write, admin) and generated from your developer dashboard. OAuth 2.0 flows are planned for Q3.

POST/v1/auth/token

Exchange your API key for a short-lived Bearer token. Tokens expire after 24 hours.

Request Body

json

{
  "api_key": "fann_live_sk_xxxxxxxxxxxx",
  "scope": ["artworks:read", "marketplace:write"]
}

Preview Only

Response

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-04-08T12:00:00Z",
  "scope": ["artworks:read", "marketplace:write"],
  "token_type": "Bearer"
}

Preview Only

DELETE/v1/auth/tokenAuth required

Invalidate the current Bearer token immediately. Use on logout or key rotation.

Response

json

{
  "revoked": true,
  "revoked_at": "2026-04-07T09:14:33Z"
}

Preview Only

Users & Profiles

Retrieve and update user profiles, preferences, and social connections within the FANN ecosystem.

GET/v1/users/meAuth required

Returns the authenticated user's full profile including tier, badges, and wallet address.

Response

json

{
  "id": "usr_7x9kmp",
  "username": "amara_creates",
  "display_name": "Amara Kweku",
  "email": "amara@example.com",
  "role": "artist",
  "tier": "gold",
  "wallet_address": "0x4B9f3C2...",
  "badges": ["certified_artist", "early_adopter"],
  "fann_points": 2840,
  "created_at": "2025-11-02T08:22:11Z"
}

Preview Only

GET/v1/users/:id

Fetch a public profile by user ID. Returns public-facing data only.

Response

json

{
  "id": "usr_7x9kmp",
  "username": "amara_creates",
  "display_name": "Amara Kweku",
  "role": "artist",
  "tier": "gold",
  "artworks_count": 34,
  "followers_count": 1209,
  "bio": "Contemporary visual artist exploring identity and diaspora.",
  "avatar_url": "https://cdn.fann.art/avatars/usr_7x9kmp.jpg"
}

Preview Only

PATCH/v1/users/:id/profileAuth required

Update a user's public profile fields. Only the authenticated user can update their own profile.

Request Body

json

{
  "display_name": "Amara K.",
  "bio": "Visual artist. FANN certified since 2025.",
  "location": "Accra, Ghana",
  "website": "https://amarakweku.art"
}

Preview Only

Response

json

{
  "id": "usr_7x9kmp",
  "display_name": "Amara K.",
  "bio": "Visual artist. FANN certified since 2025.",
  "location": "Accra, Ghana",
  "website": "https://amarakweku.art",
  "updated_at": "2026-04-07T10:05:00Z"
}

Preview Only

Artworks

Full CRUD for artwork listings. All registered artworks go through FANN's blockchain certification pipeline.

GET/v1/artworks

List all public artworks with pagination, filtering by medium, price range, artist, and certification status.

Response

json

{
  "data": [
    {
      "id": "art_9k2mxp",
      "title": "Solitude in Blue",
      "artist_id": "usr_7x9kmp",
      "year": 2023,
      "medium": "Oil on canvas",
      "price_usd": 12500,
      "verified": true,
      "fractional_available": true,
      "thumbnail_url": "https://cdn.fann.art/art_9k2mxp/thumb.jpg"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 4328 }
}

Preview Only

GET/v1/artworks/:id

Retrieve full artwork metadata, provenance history, certificate hash, and all associated media.

Response

json

{
  "id": "art_9k2mxp",
  "title": "Solitude in Blue",
  "artist": { "id": "usr_7x9kmp", "name": "Amara Kweku" },
  "year": 2023,
  "medium": "Oil on canvas",
  "dimensions": { "width": 90, "height": 120, "unit": "cm" },
  "description": "An exploration of solitude...",
  "certificate_hash": "0xf4a3b9c2d1e8f7a6b5c4d3e2f1a0b9c8",
  "verified": true,
  "price_usd": 12500,
  "provenance": [
    { "event": "created", "date": "2023-05-14", "actor": "Amara Kweku" },
    { "event": "certified", "date": "2023-06-01", "tx": "0xabc123..." }
  ]
}

Preview Only

POST/v1/artworksAuth required

Request Body

json

{
  "title": "Golden Horizon",
  "year": 2026,
  "medium": "Acrylic on linen",
  "dimensions": { "width": 100, "height": 80, "unit": "cm" },
  "description": "A meditation on light at dusk.",
  "price_usd": 8750,
  "image_url": "https://cdn.fann.art/uploads/tmp_xyz.jpg"
}

Preview Only

Response

json

{
  "id": "art_n3r8qt",
  "title": "Golden Horizon",
  "status": "pending_certification",
  "certificate_hash": null,
  "estimated_certification_time": "2–5 minutes",
  "created_at": "2026-04-07T11:00:00Z"
}

Preview Only

PATCH/v1/artworks/:idAuth required

Update artwork metadata. Only the owning artist or an admin may update. Certified fields are immutable.

Request Body

json

{
  "price_usd": 15000,
  "description": "Updated provenance notes included.",
  "for_sale": true
}

Preview Only

Response

json

{
  "id": "art_9k2mxp",
  "price_usd": 15000,
  "for_sale": true,
  "updated_at": "2026-04-07T11:30:00Z"
}

Preview Only

DELETE/v1/artworks/:idAuth required

Soft-delete an artwork listing. The blockchain certificate and provenance record remain immutable.

Response

json

{
  "deleted": true,
  "id": "art_9k2mxp",
  "certificate_preserved": true,
  "deleted_at": "2026-04-07T12:00:00Z"
}

Preview Only

GET/v1/artworks/:id/certificate

Retrieve the full blockchain certificate for an artwork, including on-chain transaction details.

Response

json

{
  "artwork_id": "art_9k2mxp",
  "certificate_hash": "0xf4a3b9c2d1e8f7a6b5c4d3e2f1a0b9c8",
  "issued_at": "2023-06-01T14:22:00Z",
  "chain": "Ethereum",
  "contract_address": "0xFANN1234...",
  "token_id": 2291,
  "verified": true,
  "issuer": "FANN Foundation"
}

Preview Only

Marketplace

Browse, list, and transact on FANN's primary and secondary art marketplace. All offers and payments are logged immutably.

GET/v1/marketplace/listings

List all active marketplace listings. Supports filters: price_min, price_max, medium, artist_id, sort.

Response

json

{
  "data": [
    {
      "listing_id": "lst_4p2qrs",
      "artwork_id": "art_9k2mxp",
      "title": "Solitude in Blue",
      "seller_id": "usr_7x9kmp",
      "price_usd": 15000,
      "currency": "USD",
      "accepts_offers": true,
      "listed_at": "2026-03-15T09:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 892 }
}

Preview Only

POST/v1/marketplace/offersAuth required

Submit a purchase offer on a listed artwork. Requires buyer authentication. Seller is notified instantly.

Request Body

json

{
  "listing_id": "lst_4p2qrs",
  "offer_amount_usd": 13500,
  "message": "I love this piece — open to negotiation.",
  "expires_in_hours": 48
}

Preview Only

Response

json

{
  "offer_id": "off_8z1wxy",
  "listing_id": "lst_4p2qrs",
  "buyer_id": "usr_abc123",
  "offer_amount_usd": 13500,
  "status": "pending",
  "expires_at": "2026-04-09T11:00:00Z",
  "created_at": "2026-04-07T11:00:00Z"
}

Preview Only

GET/v1/marketplace/transactionsAuth required

Retrieve transaction history for the authenticated user, including purchases, sales, and royalty payouts.

Response

json

{
  "data": [
    {
      "tx_id": "txn_5r3mnp",
      "type": "sale",
      "artwork_id": "art_9k2mxp",
      "amount_usd": 13500,
      "status": "completed",
      "buyer_id": "usr_abc123",
      "seller_id": "usr_7x9kmp",
      "completed_at": "2026-04-05T16:44:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 47 }
}

Preview Only

Fractional Ownership

FANN's fractional ownership system allows collectors to buy tokenised shares in high-value artworks. All share data is on-chain.

GET/v1/fractional/artworks

List artworks available for fractional investment, including total shares, price per share, and funding progress.

Response

json

{
  "data": [
    {
      "artwork_id": "art_9k2mxp",
      "title": "Solitude in Blue",
      "total_shares": 1000,
      "shares_available": 340,
      "price_per_share_usd": 15,
      "total_value_usd": 15000,
      "funded_pct": 66,
      "artist": "Amara Kweku"
    }
  ]
}

Preview Only

GET/v1/fractional/:id/shares

List all fractional share holders for a specific artwork, with ownership percentages.

Response

json

{
  "artwork_id": "art_9k2mxp",
  "total_shares": 1000,
  "shareholders": [
    {
      "user_id": "usr_abc123",
      "shares_owned": 150,
      "ownership_pct": 15.0,
      "acquired_at": "2026-02-20T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 23 }
}

Preview Only

POST/v1/fractional/:id/purchaseAuth required

Purchase fractional shares in an artwork. Payment is processed and shares are minted on-chain.

Request Body

json

{
  "shares_quantity": 50,
  "payment_method_id": "pm_stripe_xxxx"
}

Preview Only

Response

json

{
  "purchase_id": "frac_7q4rst",
  "artwork_id": "art_9k2mxp",
  "shares_purchased": 50,
  "total_paid_usd": 750,
  "on_chain_tx": "0xmint99aa...",
  "new_ownership_pct": 5.0,
  "status": "confirmed",
  "created_at": "2026-04-07T12:00:00Z"
}

Preview Only

Community

Access FANN's community features: posts, discussions, challenges, and artist spotlights.

GET/v1/community/posts

List community posts with optional filters: type (artwork|discussion|challenge), author_id, tag.

Response

json

{
  "data": [
    {
      "post_id": "pst_3k8lmn",
      "type": "artwork_share",
      "author_id": "usr_7x9kmp",
      "content": "Excited to share my latest piece!",
      "artwork_id": "art_9k2mxp",
      "likes_count": 142,
      "comments_count": 28,
      "created_at": "2026-04-06T08:00:00Z"
    }
  ]
}

Preview Only

POST/v1/community/postsAuth required

Create a new community post. Supports text, artwork references, and image attachments.

Request Body

json

{
  "type": "discussion",
  "content": "What techniques do you use for layering oil paints?",
  "tags": ["oil-painting", "technique", "tips"]
}

Preview Only

Response

json

{
  "post_id": "pst_9n7xyz",
  "type": "discussion",
  "author_id": "usr_7x9kmp",
  "content": "What techniques do you use for layering oil paints?",
  "tags": ["oil-painting", "technique", "tips"],
  "created_at": "2026-04-07T12:05:00Z"
}

Preview Only

GET/v1/community/discussions

List active discussion threads, sorted by recent activity or popularity.

Response

json

{
  "data": [
    {
      "discussion_id": "disc_2m5xyz",
      "title": "Best practices for digital certification",
      "author_id": "usr_abc123",
      "replies_count": 47,
      "last_activity": "2026-04-07T09:30:00Z",
      "pinned": false
    }
  ]
}

Preview Only

GET/v1/community/challenges

List active and upcoming creative challenges. Includes prize pools, submission deadlines, and participant counts.

Response

json

{
  "data": [
    {
      "challenge_id": "chl_6r1stv",
      "title": "Spring Palette Challenge 2026",
      "theme": "Nature & Renewal",
      "prize_pool_usd": 5000,
      "submissions_count": 318,
      "deadline": "2026-04-30T23:59:00Z",
      "status": "active"
    }
  ]
}

Preview Only

Rewards

FANN Points are earned through platform activity and redeemable for discounts, exclusive drops, and premium features.

GET/v1/rewards/balanceAuth required

Retrieve the authenticated user's current FANN Points balance and tier status.

Response

json

{
  "user_id": "usr_7x9kmp",
  "fann_points": 2840,
  "tier": "gold",
  "tier_threshold_next": 5000,
  "points_to_next_tier": 2160,
  "lifetime_earned": 4120
}

Preview Only

GET/v1/rewards/historyAuth required

Paginated history of FANN Points earned and redeemed.

Response

json

{
  "data": [
    {
      "event_id": "rev_8p2qrs",
      "type": "earned",
      "points": 200,
      "reason": "artwork_certified",
      "reference_id": "art_9k2mxp",
      "created_at": "2026-03-01T14:00:00Z"
    },
    {
      "event_id": "rev_7n1abc",
      "type": "redeemed",
      "points": -500,
      "reason": "discount_applied",
      "reference_id": "ord_xyz789",
      "created_at": "2026-03-20T10:00:00Z"
    }
  ]
}

Preview Only

POST/v1/rewards/redeemAuth required

Redeem FANN Points for a reward. Returns a redemption code or applies discount to a pending order.

Request Body

json

{
  "reward_id": "rwd_premium_month",
  "points_to_spend": 1000
}

Preview Only

Response

json

{
  "redemption_id": "rdm_5t3uvw",
  "reward": "Premium membership — 1 month",
  "points_spent": 1000,
  "remaining_balance": 1840,
  "activation_code": "FANN-PREM-A4X9",
  "redeemed_at": "2026-04-07T12:10:00Z"
}

Preview Only

Events

Browse FANN platform events: exhibitions, live auctions, artist talks, and virtual gallery openings.

GET/v1/events

List upcoming and past events. Filter by type, location, date range, and featured status.

Response

json

{
  "data": [
    {
      "event_id": "evt_3h7klm",
      "title": "FANN Annual Showcase 2026",
      "type": "exhibition",
      "format": "hybrid",
      "location": "Lagos, Nigeria + Virtual",
      "starts_at": "2026-06-15T10:00:00Z",
      "ends_at": "2026-06-20T20:00:00Z",
      "artists_count": 84,
      "featured": true
    }
  ]
}

Preview Only

GET/v1/events/:id

Retrieve full details for a single event, including schedule, speakers, participating artists, and ticket info.

Response

json

{
  "event_id": "evt_3h7klm",
  "title": "FANN Annual Showcase 2026",
  "description": "The premier celebration of African contemporary art...",
  "type": "exhibition",
  "format": "hybrid",
  "location": "Lagos, Nigeria + Virtual",
  "starts_at": "2026-06-15T10:00:00Z",
  "ends_at": "2026-06-20T20:00:00Z",
  "artists": [
    { "id": "usr_7x9kmp", "name": "Amara Kweku" }
  ],
  "tickets": {
    "virtual": { "price_usd": 0, "available": true },
    "in_person": { "price_usd": 45, "available": true, "remaining": 120 }
  }
}

Preview Only

Admin & Webhooks

Admin endpoints require an admin-scoped API token. Webhooks allow you to subscribe to platform events in real time.

GET/v1/admin/usersAuth required

List all platform users with full metadata. Supports search, filter by role/tier/status, and pagination.

Response

json

{
  "data": [
    {
      "id": "usr_7x9kmp",
      "email": "amara@example.com",
      "role": "artist",
      "tier": "gold",
      "status": "active",
      "joined_at": "2025-11-02T08:22:11Z",
      "last_login": "2026-04-07T08:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 18420 }
}

Preview Only

POST/v1/admin/artworks/:id/verifyAuth required

Admin-only: manually trigger or approve blockchain certification for an artwork.

Request Body

json

{
  "override_reason": "Manual certification after physical inspection",
  "inspector_id": "adm_review_001"
}

Preview Only

Response

json

{
  "artwork_id": "art_n3r8qt",
  "status": "certified",
  "certificate_hash": "0xnew88bb...",
  "certified_at": "2026-04-07T13:00:00Z",
  "certified_by": "adm_review_001"
}

Preview Only

GET/v1/admin/reportsAuth required

Access platform-level analytics reports: revenue, user growth, artwork volume, and dispute summaries.

Response

json

{
  "period": "2026-Q1",
  "new_users": 3421,
  "artworks_certified": 892,
  "total_volume_usd": 1240000,
  "active_disputes": 14,
  "challenges_completed": 6,
  "generated_at": "2026-04-07T00:00:00Z"
}

Preview Only

Webhooks

Subscribe to FANN platform events via webhooks. Register your endpoint URL in your developer dashboard. FANN will POST a signed JSON payload to your URL for each subscribed event. Verify the X-FANN-Signature header to confirm authenticity.

Webhook Registration

curl

curl -X POST https://api.fann.art/v1/webhooks \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/fann",
    "events": ["artwork.certified", "offer.accepted", "payment.completed"]
  }'

Preview Only

EVENTartwork.certified

Fires when an artwork's blockchain certificate is issued. Payload includes certificate_hash and token_id.

Example Payload

json

{
  "event": "artwork.certified",
  "artwork_id": "art_9k2mxp",
  "certificate_hash": "0xf4a3b9...",
  "certified_at": "2026-04-07T14:00:00Z"
}

Preview Only

EVENToffer.accepted

Fires when a seller accepts a buyer's marketplace offer. Initiates the payment collection flow.

Example Payload

json

{
  "event": "offer.accepted",
  "offer_id": "off_8z1wxy",
  "listing_id": "lst_4p2qrs",
  "amount_usd": 13500,
  "accepted_at": "2026-04-07T15:00:00Z"
}

Preview Only

EVENTpayment.completed

Fires when a transaction is fully settled and funds have been disbursed to the seller.

Example Payload

json

{
  "event": "payment.completed",
  "tx_id": "txn_5r3mnp",
  "artwork_id": "art_9k2mxp",
  "amount_usd": 13500,
  "completed_at": "2026-04-07T16:00:00Z"
}

Preview Only

EVENTchallenge.joined

Fires when a user submits an entry to a creative challenge.

Example Payload

json

{
  "event": "challenge.joined",
  "challenge_id": "chl_6r1stv",
  "user_id": "usr_7x9kmp",
  "submission_id": "sub_4m2nop",
  "joined_at": "2026-04-07T17:00:00Z"
}

Preview Only

FANN Developer API

Authentication

Users & Profiles

Artworks

Marketplace

Fractional Ownership

Community

Rewards

Events

Admin & Webhooks

Webhooks

Webhook Registration