# API

_Named same-origin APIs used by Homepage Apps._

## Contract

Homepage APIs are single-purpose adapters. Apps call the documented same-origin route; Homepage validates the request, resolves credentials server-side, and returns a shared response envelope. API registrations in App manifests describe dependencies and capability identity but do not dynamically create routes or proxies.

## Response envelope

Success responses use:

```json [v nowrap]
{ "ok": true, "data": {}, "error": null }
```

Failures use ok: false, data: null, and error: { code, message, details? }. The message is safe for users; details are optional and bounded. Credentials, raw provider responses, and provider-specific secrets are never returned.

## Current routes

| Capability | Method | Route | Credential |
| --- | --- | --- | --- |
| Image Generator | POST | /api/image-generator | openai-image, resolved by Homepage |
| Maps address | POST | /api/maps/address | None |
| Maps point | POST | /api/maps/point | None |
| Maps route | POST | /api/maps/route | None |
| Maps area | POST | /api/maps/area | None |

The [Apps](https://homepage.sefzig-net.workers.dev/docs/apps) contract documents request shapes, capability registration, and the bridge status flow. Provider/API validity is reported separately through homepage/app/api-status; a credential_missing result refreshes capability status to missing rather than proving that a previous request was configured correctly.