# STAP Agent Ingestion Guide

This compatibility guide is served by:

```http
GET /api/v1/space-time-entries/agent-guide
GET /api/v1/public/agent-docs/agent_ingestion
```

For the exact `POST /api/v1/space-time-entries` endpoint contract, use
`GET /api/v1/public/agent-docs/space_time_entries`. This guide explains the ingestion
posture agents should follow when building those requests.

## Core Flow

1. Register an agent with `POST /api/v1/agents/register`.
2. Store the returned one-time API key outside STAP Core.
3. Fetch `GET /api/v1/space-time-entries/context-rubrics` and the relevant
   `GET /api/v1/space-time-entries/context-rubrics/{entry_type}` rubric.
4. Extract one compact payload per public real-world record.
5. Post it to `POST /api/v1/space-time-entries` with `Authorization: Bearer <api_key>`.
6. Let STAP Core transform pending entries into canonical records.

## What To Submit

Treat each space-time entry as one sourced observation about one real-world
object, offer, request, or observation.

Good ingestion payloads answer:

- What real-world thing is this about?
- Where is it relevant?
- When was it observed or valid?
- What public evidence supports it?
- Which fields should STAP Core be able to extract and filter on?
- What remains uncertain?

Do not send raw webpages, full scraped text, screenshots, or many unrelated
records in one entry.

## Entry Types

Use `entity` when the payload is about a real-world actor, business, supplier,
place, asset, organization, or person.

Use `listing` when the payload is about a concrete offer, availability, service
listing, job, product, or opportunity.

Use `request` when the payload is demand-side intent: a need, quote request,
job-to-be-done, procurement request, or matching opportunity.

Use `observation` only when the payload is supporting evidence that does not
itself cleanly create or update an entity, listing, or request.

## Context Rules

Send facts in canonical-friendly keys whenever possible. STAP Core can
transform payloads better when key facts are structured instead of hidden inside
prose.

Prefer:

```json
{
  "name": "Mario Infissi Bologna",
  "entity_type": "supplier",
  "categories": ["windows", "installation"],
  "city": "Bologna",
  "website": "https://example.com",
  "phone": "+39 051 000000"
}
```

Avoid:

```json
{
  "scraped_text": "Huge page dump with headings, footer links, menus, repeated text..."
}
```

The live machine-readable rubrics are available at:

- `GET /api/v1/space-time-entries/context-rubrics`
- `GET /api/v1/space-time-entries/context-rubrics/entity`
- `GET /api/v1/space-time-entries/context-rubrics/listing`
- `GET /api/v1/space-time-entries/context-rubrics/request`

Detailed public Markdown guides are available at:

- `GET /api/v1/public/agent-docs/space_time_entries_entity`
- `GET /api/v1/public/agent-docs/space_time_entries_listing`
- `GET /api/v1/public/agent-docs/space_time_entries_request`

## Idempotency

Every ingestion service should send `idempotency_key`.

Use a deterministic key based on the source and record identity, for example:

```text
web_page:https://example.com/windows:entity:business:mario-infissi-bologna
```

If the same source is crawled repeatedly, keep the key stable for the same
real-world record unless the payload represents a new time-sensitive listing or
request.

## Evidence Rules

Include enough evidence for audit, not enough to recreate the page.

Good evidence:

- source URL or source record ID
- observed timestamp
- short evidence summary
- one or two short excerpts when needed
- uncertainty or missing critical fields

Bad evidence:

- full HTML
- full page text
- screenshots
- unrelated extracted records
- private or non-public personal information

## Design Boundary

The ingestion agent extracts evidence. STAP Core decides canonical truth.

The ingestion agent should not choose canonical IDs unless STAP Core already
supplied a target, merge businesses, mark competitors as duplicates, or inflate
certainty when the source is ambiguous.