Single reference for building and submitting plugins: from "what is SwarmSpace?" through a working submission. Copy the JSON and curl examples directly.
SwarmSpace is a plugin marketplace where the primary consumer is the AI agent, not the end user. Humans choose clients; agents discover tools at runtime, decide relevance, and invoke them.
One capability, one clear input contract, one structured output. Examples: web search, weather, summarization, sentiment, translation.
An ordered list of plugin invocations where each step's output feeds the next. Published with a manifest plus a workflow_steps array (plugin slugs in order).
| Workflow trust | Plugin chain rules |
|---|---|
| Community | May only chain free-tier plugins. |
| Verified | May chain free and paid plugins. |
The manifest is the machine-readable contract agents use to decide whether to call your tool. Write for LLM consumption: precise, unambiguous, no filler.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable name. Max 60 characters. |
description | string | Yes | What the plugin does and what it returns. Primary matching text for agents. 50–500 characters. |
agent_guidance | string | No | When to use it; what it pairs with. Max 300 characters. |
access_tier | string | Yes | One of: free, standard, premium. Declares which SwarmSpace access tier is required to invoke the plugin. |
trust_tier | string | Read-only | Assigned after review: community or verified. Omit or leave unset on submit; SwarmSpace sets this. |
credit_cost_per_call | number | Conditional | Credits per call. 0 for free plugins. Required when the plugin charges credits. Ceilings by category: search/lookup 5, data enrichment 15, AI synthesis 30, complex multi-step 50. |
semantic_tags | string[] | Yes | Discovery tags. Min 2, max 10. Prefer specific tokens (e.g. academic-paper-search) over generic ones (search). |
latency_class | string | Yes | fast (typical <1s), standard (1–5s), slow (>5s). Platform expects responses within the SLA in Section 4 regardless of label. |
privacy_data_required | string[] | Yes | Dot-notation CHRONICLE field names this plugin needs access to (e.g. ["location"], ["user.display_name", "user.email"]). Use [] or ["none"] if no personal data is required. Drives PRISM minimization at the sandbox boundary — only declared fields are forwarded to your plugin. See Section 10 for the full vocabulary. |
auth_method | string | Yes | none, api_key, or oauth. |
endpoint_url | string | Yes | HTTPS URL SwarmSpace calls with POST and JSON body. |
canonical_url | string | Auto | Stable URL for agent-to-agent references. Generated by SwarmSpace; do not hand-roll. |
network_domains | string[] | Yes | Hostnames your implementation calls outbound (no scheme). Used for allowlisting, e.g. ["api.open-meteo.com"]. |
content_hash | string | Auto | Integrity hash of submitted artifact; set by platform. |
risk_tier | string | Assigned | low, medium, high. Set during review. |
schedulable | boolean | No | Whether the plugin may be invoked on a recurring schedule (Durable Objects). Default false. Only Verified plugins may set true. |
is_read_only | boolean | No | Plugin only reads data, never modifies state. Default true. |
is_destructive | boolean | No | Plugin may modify or delete user data. Default false. |
is_concurrency_safe | boolean | No | Plugin is safe to call in parallel. Default true. |
headless | boolean | No | Plugin can run without user interaction. Required for Durable Object dispatch. Default false. |
workflow_steps | string[] | Workflows only | Ordered plugin slugs composing the workflow. Omit for atomic plugins. |
Use this for validation in CI or editors that support JSON Schema.
Paid plugins must set credit_cost_per_call within the category ceilings in Section 3.1; free plugins use 0.
Replace slugs with your actual registered plugin IDs. Community workflows must only reference free access_tier plugins.
Available context fields for privacy_data_required declaration. Only fields listed here may be included in the array. Use dot-notation to reference nested fields.
| Field | Category | Description |
|---|---|---|
user.display_name | Identity | User's display name |
user.email | Identity | User's email address |
user.timezone | Identity | User's timezone |
user.location | Location | User's location/city |
user.language | Preferences | User's preferred language |
chronicle.interests | Preferences | User's interest topics |
chronicle.goals | Preferences | User's stated goals |
Only declared fields are forwarded to plugins. If your plugin does not need personal data, set privacy_data_required to [] or ["none"].
Your endpoint must:
Content-Type: application/json.query (string).latency_class:
endpoint_url. Uptime feeds merit scoring.All requests from SwarmSpace carry an Authorization: Bearer <token> header. Validate this token to confirm the request originates from SwarmSpace.
SwarmSpace sends a POST to your endpoint_url. Cloudflare Workers accept requests at /invoke or / paths.
The request body varies by plugin. At minimum your endpoint should accept a query string. Optional fields like limit are plugin-specific. Additional request parameters are defined by your plugin's contract.
Return an appropriate HTTP error status (4xx or 5xx) with a JSON body:
Expect an HTTP 4xx/5xx status with { "error": "..." } if validation fails.
SwarmSpace enforces a 25-second hard timeout on all plugin invocations. Plugins that exceed this receive a 504 Gateway Timeout. Design your endpoint to respond within the latency SLA for your declared latency_class (fast: 1s, standard: 5s, slow: 30s). The hard timeout applies regardless of latency_class.
SwarmSpace returns structured error responses with both a human-readable error message and a machine-readable code. Your client code should check the code field:
| Error | Code | Meaning |
|---|---|---|
{ "error": "PRISM_CONSENT_REQUIRED", "code": "CONSENT_REQUIRED" } | CONSENT_REQUIRED | PRISM consent needed — the user has not consented to sharing the requested personal data fields with this plugin. |
{ "error": "Plugin not found", "code": "NOT_FOUND" } | NOT_FOUND | Unknown plugin_id — the requested plugin does not exist in the registry. |
{ "error": "Insufficient tier", "code": "FORBIDDEN" } | FORBIDDEN | Tier too low — the user's access tier does not permit invocation of this plugin. |
{ "error": "Rate limit exceeded", "code": "RATE_LIMITED" } | RATE_LIMITED | Credit ceiling hit — the user has exceeded their daily or monthly invocation limit. |
{ "error": "Plugin invocation failed: ...", "code": "UPSTREAM_ERROR" } | UPSTREAM_ERROR | Worker error — the plugin endpoint returned an error or was unreachable. |
{ "error": "Request timeout", "code": "TIMEOUT" } | TIMEOUT | 25s timeout exceeded — the plugin did not respond within the hard timeout. |
| Stage | What happens | Timeline |
|---|---|---|
| 1. Submit | Complete the form at submit-plugin.html. Manifest fields are validated; endpoint reachability is checked. | Immediate |
| 2. Automated checks | Schema validation, response shape checks, latency sampling vs latency_class. | Minutes |
| 3. Safety review | Human review: abuse, third-party ToS alignment, privacy minimization, identity checks. | 2–3 business days |
| 4. Listing | Community tier; discoverable via agent search and catalogue updates. | After approval |
| 5. Monthly merit review | Strong Community plugins evaluated for Verified promotion. | Monthly |
privacy_data_required lists fields the implementation does not actually use (PRISM violation).network_domains.description so agents cannot route to the tool reliably.Submission requires accepting the SwarmSpace Developer Agreement and third-party API compliance (see checkbox on the submission form). There is no separate legal copy in this repository; the binding step is the in-flow acceptance at submit time.
| Tier | How you get it | What it means |
|---|---|---|
| Community | Pass safety review | Listed; free to users; no credit charging; standard placement. |
| Verified | Merit promotion (monthly) | Top placement in category search; may charge credits; 80% revenue share to you; eligible for schedulable: true. |
Verified is not for sale. Placement and tier are earned, not purchased. That constraint is structural to SwarmSpace's trust model.
Monthly Verified consideration uses a composite score. No single signal alone should dominate.
| Signal | Weight | What it measures |
|---|---|---|
| Upvotes | Medium | Community endorsement; one vote per user per plugin; voter quality weighted by usage history. |
| Call volume | High | Actual agent invocations. |
| Retention | High | Repeat use across sessions. |
| Developer activity | Medium | Posts and support in the plugin's Swarm community space. |
| Update frequency | Low | Maintenance; stale plugins decay. |
| Error rate | Disqualifying | Sustained high failure rates remove eligibility regardless of other signals. |
credit_cost_per_call (within ceilings). 80% of credits to you, 20% to SwarmSpace.Active publishers receive SwarmSpace Pro (nominal $15/mo value) at no charge while eligible:
If you have no published plugins in good standing for 90 days, entitlement reverts to standard consumer pricing/policy.
Enforcement is currently logging-only: the router logs privacy events (e.g. unconsented data access attempts) but does not yet block requests. Active enforcement is planned for a future release.
privacy_data_required receive user context. Only the specific CHRONICLE fields declared in the array are forwarded to your plugin — no other user data is included. The sandbox boundary (pre-deployed Cloudflare Workers at fixed URLs) enforces the allowlist. Use [] or ["none"] if your plugin needs no personal data.network_domains are whitelisted. (Internal docs refer to globalOutbound: null until explicitly configured.)Full detail: PRISM Technical Documentation
The privacy_data_required field is a string array of dot-notation CHRONICLE field names as described in Section 3.1. Only declared fields are forwarded to plugins. See the context field vocabulary for valid field names.
POST endpoint; return the JSON envelope in Section 4.manifest.json using Section 3 (host at manifest URL if you use the optional field on the form).curl against your endpoint.