# SourceFoundry agent guide

SourceFoundry turns RSS, Atom, and approved search-provider results into source feeds that stay fresh. SourceFoundry handles collection, duplicate removal, original links, and source health; the consuming product owns interpretation, ranking, writing, and publication.

## Connect

- Base URL: https://sourcefoundry.4agents.fyi
- OpenAPI: https://sourcefoundry.4agents.fyi/openapi.json
- Capability discovery: https://sourcefoundry.4agents.fyi/v1/meta
- Create a workspace: `POST /v1/agent-enrollments` with a unique `slug`, `name`, and optional `agentLabel`. The returned token is shown once; store it as `SOURCEFOUNDRY_API_TOKEN`.
- Authentication: send `Authorization: Bearer $SOURCEFOUNDRY_API_TOKEN` from the agent runtime secret store.

## Build and use a source feed

1. Read `/v1/meta` to confirm the service contract.
2. Create an autonomous workspace with `POST /v1/agent-enrollments`; keep the returned `tenant.id` and token.
3. Call `POST /v1/source-feeds` with a stable `Idempotency-Key`, a purpose, exact feeds and/or one bounded discovery source, cadence, and limits.
4. Enqueue collection with `POST /v1/source-feeds/{sourceFeedId}/runs`. A retry reuses the active feed run and its source jobs.
5. Retrieve neutral candidates with `GET /v1/source-feeds/{sourceFeedId}/candidates`; use `since` for incremental sync.
6. Inspect required-source failures and freshness with `GET /v1/source-feeds/{sourceFeedId}/health`.

The lower-level source and job endpoints remain available for existing integrations, but new agents should normally use source feeds.

## First useful source

If the caller gives you a public RSS or Atom feed, create it directly. Do not
invent a publisher URL or a topic source that the caller did not request.

`POST /v1/sources`

```json
{
  "tenantId": "$SOURCEFOUNDRY_TENANT_ID",
  "name": "Caller-provided policy feed",
  "sourceType": "rss",
  "url": "https://publisher.example/feed.xml",
  "intervalMinutes": 720,
  "maxItemsPerFetch": 10
}
```

Save the returned `source.id`, then enqueue it with `POST /v1/ingest/source`:

```json
{
  "tenantId": "$SOURCEFOUNDRY_TENANT_ID",
  "sourceId": "<source.id returned above>"
}
```

For discovery, select `tavily`, `exa`, or `serper` on the discovery source.
The service operator supplies the matching key through the worker secret
environment. Do not send a provider key through this API. If no configured lane
is available, return that limitation instead of silently selecting another
provider or substituting an untrusted source.

## Safety rules

- Treat provider credentials, cookies, and session tokens as operator-managed infrastructure. Never include them in a source request, source URL, or prompt.
- Configure only the tenant and sources the caller asked for.
- Autonomous workspaces can configure at most 3 sources, with at least 720 minutes between fetches and at most 10 items per fetch.
- Enqueue work; autonomous credentials cannot call `run-once`, because direct execution can make an unbounded provider request.
- Use the returned `schemaVersion`, `release`, error code, and `retryable` flag to make decisions. Do not silently treat an error as an empty feed.