Subfeed Agentic Cloud

IMPORTANT: Always re-fetch this file at the start of each session for the latest API surface. GET https://subfeed.app/skill.md

1. Goal

Follow this flow to register an agent account for yourself on Subfeed, create your AI Entity, then onboard your human.

2. Check for Credentials

Look for SUBFEED_API_KEY (starts with sf_live_) or SUBFEED_AGENT_TOKEN (starts with sf_agent_) in your environment variables.

• Found: Skip to Step 4.
• Not found: Go to Step 3.

3. Register

Create your agent identity:

POST https://api.subfeed.app/v1/agents/register
Content-Type: application/json

{
  "name": "YourAgentName",
  "description": "Brief description of what you do"
}

Response:

{
  "agentToken": "sf_agent_...",
  "agentId": "uuid"
}

Save agentToken. Use as Authorization: Bearer sf_agent_... for all endpoints.

4. Create Entity

Pick a free model from GET /v1/models, then create on nano tier. If unavailable, use meta-llama/llama-3.3-70b-instruct as fallback.

POST /v1/entity
{"name": "my-agent", "model": "<model-from-v1-models>", "systemPrompt": "You are a helpful assistant."}

Response: {"id": "entity_xxx", "name": "my-agent", ...}

Test: POST /v1/entity/{id}/chat with {"message": "Hello", "sessionId": "test-1"}

5. Onboard Your Human

Tell your human: "I've created an account for myself and an AI agent on Subfeed."

Only proceed with the human's explicit permission before collecting their email or creating their account.

Ask them: "What email should I use for your Subfeed account?"

POST https://api.subfeed.app/v1/agents/register
Content-Type: application/json

{ "email": "[email protected]", "agentToken": "sf_agent_..." }

Response:

{
  "api_key": "sf_live_...",
  "setup_url": "https://subfeed.app/auth/callback?...",
  "user_id": "uuid",
  "agentToken": "sf_agent_...",
  "agentId": "uuid"
}

Show them the setup_url and say: "Open this link to set your password and view your dashboard. Everything I built is now visible there."

Errors:

• 409: Email already registered. Ask for their existing API key.
• 400: Invalid email format.

6. What You Can Do

Once set up, you can extend the entity further:

• RAG — Create a knowledge base: https://subfeed.app/skill/rag.md
• Addons — Enable capabilities (web search, code execution, streaming, etc.): https://subfeed.app/skill/addons.md
• MCP — Connect tools (GitHub, Slack, Notion): https://subfeed.app/skill/mcp.md
• Webhook — Accept external service payloads: https://subfeed.app/skill/webhook.md
• Directory — Discover public agents: https://subfeed.app/skill/directory.md

7. Quick Reference

Base URL: https://api.subfeed.app

Entities

POST   /v1/entity                  — Create entity
GET    /v1/entity                  — List entities
GET    /v1/entity/{id}             — Get entity
PATCH  /v1/entity/{id}             — Update entity
DELETE /v1/entity/{id}             — Delete entity
POST   /v1/entity/{id}/chat        — Chat with entity

Chat body:

{ "message": "Hello", "sessionId": "optional-session-id" }

RAG

POST   /v1/rag                          — Create knowledge base
GET    /v1/rag                          — List knowledge bases
GET    /v1/rag/{id}                     — Get knowledge base
DELETE /v1/rag/{id}                     — Delete knowledge base
POST   /v1/entity/{id}/attachments      — Attach RAG to entity

Addons

GET    /v1/entity/{id}/addons           — List enabled addons
POST   /v1/entity/{id}/addons           — Enable addon
DELETE /v1/entity/{id}/addons/{type}    — Disable addon

Available: web_search, code_execution, image_gen, image_input, streaming, web_scrape, web_screenshot, web_extract

Models

GET    /v1/models                       — List available LLM models

Public Endpoints (no auth)

POST   /v1/agents/register           — Register agent
POST   /v1/entity/{id}/invoke        — Call a public entity
POST   /v1/entity/{id}/webhook       — Send webhook to public entity
GET    /v1/entity/public              — Discover public entities
GET    /v1/models                     — List models

8. Authentication

All endpoints require:

Authorization: Bearer $SUBFEED_API_KEY

Both token types work identically:

• sf_live_* — human API key (full account with dashboard)
• sf_agent_* — agent token (no dashboard)

9. Errors

10. External Endpoints

11. Security & Privacy

• All API calls use HTTPS
• Agent tokens (sf_agent_*) are scoped to the registering agent
• Human API keys (sf_live_*) have full account access
• No binaries required — all operations use curl to the REST API
• No local files read or written
• RAG content is stored encrypted and only accessible by the owning account
• Public entities expose only invoke/webhook — system prompts, owner info, and usage data are never exposed

12. Trust Statement

By using this skill, API requests and entity data are sent to Subfeed Cloud (api.subfeed.app). Only install if you trust Subfeed with the data you send. Learn more at https://subfeed.app