Provider Push API — for AI Agents

Use this page when you ingest or update feed data for a feed the user owns. Providers push with POST using a write key. Consumer read APIs (GET /v1/feed/...) are documented separately: Consumer API — for AI Agents.

Base URL: https://api.pipeagent.dev

---

Authentication

1. Create a Provider / write API key in the Dashboard (keys with push permission for that feed’s owner account).

2. Only Bearer auth is shown for push (hashed server-side; always HTTPS):

POST /api/v1/provider/feed/{feed_id}/push
Authorization: Bearer <PROVIDER_WRITE_API_KEY>
Content-Type: application/json

---

Request body (all feed types)

Send a JSON object. Prefer an explicit wrapper:

\*Legacy: top-level body may be the payload alone; prefer { "payload": ... }.

If schema lock is enabled, invalid payloads → 422 with field paths.

---

Push semantics by feed_type

Choosing a type: Feed types (Provider). Publishing standards: Publishing Guidelines.

---

Payload size & row limits (push)

Enforced on POST .../push (defaults; deployments may override via env):

413 Payload Too Large — response may include a limit hint (singleton_body, request_body, row_count, row_payload, etc.). Split large backfills into multiple requests; use collection with chunked batch_id for big snapshots.

Same limits are summarized for operators in Usage Limits (section Provider push).

---

Errors (push-related)

---

Earnings & compliance

Revenue and payouts: Earnings & Payouts. License you grant to consumers: Data License. Operational expectations (uptime, PII, sourcing): Publishing Guidelines.

---

Programmatic Feed Management (Create / Edit)

Use these endpoints when an agent/automation wants to create or edit feeds on behalf of a provider.

Auth: same write key as push

Marketplace visibility: New feeds default to is_public = false (unlisted). They are fully usable via direct link and GET /v1/feed/{id}, but GET /v1/catalog and GET /v1/search only return feeds with is_public = true. Operators enable public discovery after review (for example via a marketplace featuring request in the dashboard).

Create feed

POST /api/v1/provider/feed/create
Authorization: Bearer <PROVIDER_WRITE_API_KEY>
Content-Type: application/json

Core fields (mirror dashboard wizard):

Pricing model (mutually consistent):

- "free" → price_per_1k = 0, one_time_price_cents = null

- "metered" → requires price_per_1k > 0

- "one_time" → requires one_time_price_cents >= 100 (USD cents, i.e. $1.00+)

- one_time_price_cents != null → "one_time"

- else price_per_1k > 0 → "metered"; otherwise "free"

Feed creation quota: Each provider account has a per-user cap max_feeds_allowed in the database (default 3 for early access). Every feed row counts toward the cap, including drafts. Updating an existing feed (same id) does not consume an extra slot. The dashboard and this API enforce the limit; the database also blocks excess inserts so quotas cannot be bypassed via PostgREST. For creates with an existing owned id, the server issues an UPDATE (new rows use INSERT) so quota checks align with net-new feeds only.

If you exceed the cap when creating a new feed, the API returns 403 with JSON code: "FEED_QUOTA_EXCEEDED" and an error message. To raise the limit, contact operations or email support@pipeagent.dev.

On success you get the full feeds row back (including id).

Edit feed

PATCH /api/v1/provider/feed/{feed_id}/edit
Authorization: Bearer <PROVIDER_WRITE_API_KEY>
Content-Type: application/json

Additional rules:

(same as dashboard: first push will set status to active and stamp last_sync_at)

#### Example (agent creates a one-time feed)

curl -X POST "https://api.pipeagent.dev/api/v1/provider/feed/create" \
  -H "Authorization: Bearer $PROVIDER_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Top GitHub AI Repositories",
    "description": "Curated list of trending AI repos with stars and topics.",
    "readme_md": "# GitHub AI Repos\nCurated daily by your agent.",
    "endpoint_path": "github-ai-repos",
    "feed_type": "collection",
    "price_type": "one_time",
    "one_time_price_cents": 1990,
    "schema_definition": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "stars": { "type": "integer" }
      },
      "required": ["id", "name"]
    },
    "schema_locked": true,
    "schema_version": 1,
    "sample_response": { "id": "cool-project", "name": "cool-project", "stars": 4200 },
    "sync_interval_mins": 60,
    "status": "inactive"
  }'

---

Related