The community data layer for compliance tools

1. Introduction

The Eyecosystems REST API provides structured, human-verified data on the Blind and Low Vision (BVI) community ecosystem. All endpoints return Production-zone records only — entities verified by the Eye Spy Foundation verification network.

Each record includes a verification timestamp, verifier attribution, and provenance chain showing when the data was last confirmed accurate. This makes the API suitable for compliance documentation and audit trails.

What you'll find in the graph

2. Authentication

The API uses header-based authentication with API keys. Include your key in the X-API-Key header with every request (except the public endpoint).

GET /v1/resources HTTP/1.1
Host: eyecosystems.polsia.app
X-API-Key: eyeco_2058df210f0a9be5c2df3dd576c88cf9b38885aa26f2d4a9
Accept: application/json

You can also pass the key as a query parameter:

GET /v1/resources?api_key=eyeco_2058df210f0a9be5c2df3dd576c88cf9b38885aa26f2d4a9 HTTP/1.1
Host: eyecosystems.polsia.app
Accept: application/json

Getting an API key

Contact us at contact@eyecosystems.polsia.app to request API access. Include your company name and intended use case. We'll issue a key within 1 business day.

3. Endpoints Reference

GET https://eyecosystems.polsia.app/v1/activity/latest

{
  "success": true,
  "data": [
    {
      "eyeco_id": "evt_jax_2024_047",
      "entity_type": "events",
      "name": "Jacksonville Braille Club Monthly Meetup",
      "ring": "Inner",
      "city_hub": "Jacksonville",
      "verified_at": "2026-04-02T14:30:00Z",
      "verified_by": " volunteer_verifier_042"
    },
    // ... 9 more records
  ],
  "count": 10
}

GET /v1/resources?city_hub=Jacksonville&ring=Inner&limit=10
X-API-Key: eyeco_xxxxxxxxxxxx

{
  "success": true,
  "data": [
    {
      "eyeco_id": "res_jax_2024_001",
      "name": "Florida School for the Deaf and Blind",
      "resource_type": "education",
      "ring": "Inner",
      "city_hub": "Jacksonville",
      "state": "FL",
      "category": "K-12 Education",
      "website_url": "https://www.fsdb.org",
      "verified_at": "2026-03-28T10:15:00Z",
      "verified_by": "verifier_007"
    }
  ],
  "count": 1,
  "total": 45,
  "limit": 10,
  "offset": 0
}

GET /v1/resources/res_jax_2024_001
X-API-Key: eyeco_xxxxxxxxxxxx

{
  "success": true,
  "data": {
    "eyeco_id": "res_jax_2024_001",
    "name": "Florida School for the Deaf and Blind",
    "resource_type": "education",
    "ring": "Inner",
    "city_hub": "Jacksonville",
    "state": "FL",
    "category": "K-12 Education",
    "website_url": "https://www.fsdb.org",
    "verified_at": "2026-03-28T10:15:00Z",
    "verified_by": "verifier_007",
    "events": [
      { "eyeco_id": "evt_jax_2024_012", "name": "FSDB Open House 2024" }
    ],
    "people": [
      { "eyeco_id": "ppl_jax_2024_003", "name": "Dr. Sarah Mitchell", "role": "Superintendent" }
    ],
    "programs": [
      { "eyeco_id": "prg_jax_2024_008", "name": "Transition Services" }
    ],
    "apps": [],
    "podcasts": [],
    "groups": [],
    "blogs": []
  }
}

GET /v1/events?city_hub=Jacksonville&limit=5
X-API-Key: eyeco_xxxxxxxxxxxx

GET /v1/people/ppl_jax_2024_003
X-API-Key: eyeco_xxxxxxxxxxxx

4. Response Format

All responses return JSON with a consistent wrapper structure.

Success Response

{
  "success": true,
  "data": /* ... response data ... */,
  "count": 10,      /* items in this response */
  "total": 145,     /* total matching records */
  "limit": 50,      /* requested limit */
  "offset": 0       /* requested offset */
}

Pagination

Use limit and offset to paginate through results. The response includes count (items in current page) and total (all matching records).

Error Responses

// 401 Unauthorized example
{
  "success": false,
  "message": "API key required. Add X-API-Key header or ?api_key= query param.",
  "docs": "https://eyecosystems.polsia.app/v1"
}

5. Data Schema

The database has 7 primary tables representing the BVI community knowledge graph. All tables include status (filter by Production), verified_at, and verified_by for provenance tracking.

Relationships

Non-resource tables (people, events, programs, apps, podcasts, groups) link to resources via parent_resource_id → resources.eyeco_id. Use /v1/resources/:id to fetch a resource with all its nested relationships in one call.

Ring Classification

Each resource is classified by its relationship to the BVI community:

• Inner — Direct service providers (schools, rehab centers)
• Inner-Outer — Community organizations (clubs, groups)
• Outer — Advocacy and government entities
• Outer-Reach — Broader accessibility ecosystem

6. Rate Limits & Pricing

API access is bundled with our tiered pricing model. Each tier includes a monthly request allowance.

Exceeding your tier's limit returns 429 Too Many Requests. Contact us to request a limit increase or custom enterprise capacity.