API_REFERENCE.md

API Reference

This document describes the public APIs and developer interfaces available within the CeloHT ecosystem.

Status: Under Active Development

As the CeloHT platform evolves, additional API endpoints and services will be documented here.

---

Overview

The CeloHT API enables developers to integrate with community services, educational resources, impact data, and blockchain-powered applications.

Design Principles

• RESTful architecture
• JSON responses
• HTTPS only
• Secure authentication
• Versioned endpoints
• Open-source documentation

---

Base URL

Production

https://api.celoht.org/v1

Development

https://dev-api.celoht.org/v1

---

Authentication

Some endpoints require authentication.

Example:

Authorization: Bearer YOUR_ACCESS_TOKEN

---

Response Format

Successful responses

{
  "success": true,
  "data": {}
}

Error responses

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Resource not found"
  }
}

---

Public Endpoints

Health Check

GET /health

Response

{
  "status": "ok",
  "version": "1.0.0"
}

---

Programs

GET /programs

Returns all active CeloHT programs.

---

Education Courses

GET /education/courses

Returns available educational courses.

---

Community Agents

GET /agents

Returns verified community agents.

---

Reforestation Campaigns

GET /reforestation

Returns active environmental initiatives.

---

Project Statistics

GET /impact

Returns ecosystem impact metrics.

---

Partners

GET /partners

Returns official partners.

---

News

GET /news

Returns latest announcements.

---

Protected Endpoints

Authentication required.

Examples:

POST /agents/register

POST /education/certificates

POST /governance/proposals

POST /governance/vote

---

Rate Limits

Default limits

• 100 requests per minute
• Burst protection enabled

Higher limits may be available for approved partners.

---

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
429	Too Many Requests
500	Internal Server Error

---

Versioning

The API uses semantic versioning.

Example

/v1/
/v2/

Breaking changes are introduced only in new major versions.

---

Security

All API traffic uses HTTPS.

Security features include:

• TLS encryption
• Authentication tokens
• Rate limiting
• Request validation
• Input sanitization
• Logging and monitoring

---

SDK Support

Future SDKs may include:

• JavaScript
• TypeScript
• Python
• Go
• Dart
• Rust

---

Example Request

curl https://api.celoht.org/v1/programs

---

Example Response

{
  "success": true,
  "data": [
    {
      "id": "education",
      "name": "Financial Education"
    },
    {
      "id": "agents",
      "name": "Agent Network"
    },
    {
      "id": "reforestation",
      "name": "Reforestation"
    }
  ]
}

---

Changelog

All API updates are documented in the project's CHANGELOG.md.

---

Support

If you discover a bug or have questions about the API:

• Open a GitHub Issue
• Start a GitHub Discussion
• Contact the CeloHT maintainers

---

License

The CeloHT API is developed as part of the CeloHT open-source ecosystem and follows the project's official licensing terms.