# Galya — agent integration skills

Use this file as a compact integration guide for coding agents and automation.

## API

- **Base URL:** `https://api.galya.io/v1`
- **Auth:** HTTP header `X-API-Key: <your-api-key>`
- **Contract:** OpenAPI 3 spec at `/openapi.yaml` on this site (same paths as below).

Representative routes (see OpenAPI for full schemas):

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/search` | Taste-ranked entity search (query params `relative_to_entity_id`, `in_terms_of_entity_type`) |
| POST | `/rerank` | Rerank candidate content for an entity |
| POST | `/ask` | Taste-personalized NL answer (when implemented) |
| POST | `/explain` | Explain affinities for agents |
| POST | `/index`, `/index/batch` | Index content into the graph |
| GET/POST/DELETE | `/entity`, `/entity/type` | Entity CRUD / types |
| GET | `/clusters`, `/cluster` | Cluster listings / detail |

## npm packages (TypeScript)

Published on npm under the `@galya` scope:

- **`@galya/schema`** — Browser event/batch types (public wire format).
- **`@galya/sdk`** — Browser SDK for capturing taste signals to your ingest endpoint.
- **`@galya/agents`** — HTTP client plus OpenAI-style **tool definitions** and **`executeGalyaAgentTool`** for wiring LLM tool calls to the REST API.

Install:

```bash
npm install @galya/schema @galya/sdk @galya/agents
```

Point the SDK at your hosted ingest URL and API key as documented in the SDK README.

## Discovery files

- **`/llms.txt`** — LLM crawler hints and canonical links.
- **`/openapi.yaml`** — Full OpenAPI specification.