Skip to content

http-api.md

Latest commit

 

History

History
423 lines (274 loc) · 8.37 KB

http-api.md

File metadata and controls

423 lines (274 loc) · 8.37 KB

StrawHub HTTP API v1

Base URL: https://strawhub.dev/api/v1/

Authentication

Most read endpoints are public. Write endpoints require a Bearer token.

Authorization: Bearer sh_xxxxx

Tokens are created via Settings > API Tokens.

Rate Limits

All rate limits are per IP address.

Bucket Limit
Read 100/min
Write 10/min
Search 30/min

A 429 response includes a Retry-After: 60 header.

Skills

List Skills

GET /api/v1/skills?limit=50&sort=updated

Query params:

  • limit (1-200, default 50)
  • sort (updated | downloads | stars)

Response:

{
  "items": [
    {
      "slug": "git-workflow",
      "displayName": "Git Workflow",
      "summary": "...",
      "stats": { "downloads": 0, "stars": 0, "versions": 1, "comments": 0 },
      "badges": {},
      "updatedAt": 1700000000000
    }
  ],
  "count": 1
}

Publish Skill (auth required)

POST /api/v1/skills
Content-Type: multipart/form-data

payload: { slug, displayName, version, changelog, dependencies?, customTags?, files[] }

The dependencies field is optional JSON: {"skills": ["security-baseline", "git-workflow==1.0.0"]}. Skills can only depend on other skills. If omitted, dependencies are read from metadata.strawpot.dependencies in the SKILL.md frontmatter.

File constraints: up to 100 files, 10 MB each, 50 MB total. Allowed extensions: .md, .txt, .json, .yaml, .yml, .toml.

Additional constraints:

  • Slug must be unique within skills.
  • If the skill already has published versions, the new version must be strictly greater than the latest.
  • Dependency validation errors are aggregated — all issues are reported together in a single error message.

Roles

List Roles

GET /api/v1/roles?limit=50&sort=updated

Query params:

  • limit (1-200, default 50)
  • sort (updated | downloads | stars)

Response shape matches List Skills.

Publish Role (auth required)

POST /api/v1/roles
Content-Type: multipart/form-data

payload: { slug, displayName, version, changelog, dependencies?, customTags?, files[] }

The dependencies field is optional JSON: {"skills": ["git-workflow==1.0.0", "code-review"], "roles": ["reviewer"]}. If omitted, dependencies are read from metadata.strawpot.dependencies in the ROLE.md frontmatter. The roles list supports "*" as a wildcard meaning "all available roles" — this is stored as-is and expanded at runtime by StrawPot.

Roles must contain exactly one file named ROLE.md.

Additional constraints:

  • Slug must be unique within roles.
  • If the role already has published versions, the new version must be strictly greater than the latest.
  • Dependency validation errors are aggregated — all issues are reported together in a single error message.

Search

Search Skills, Roles, Agents, Memories, and Integrations

GET /api/v1/search?q=review&kind=all&limit=20

Query params:

  • q (required) — search query
  • kind (all | skill | role | agent | memory | integration, default all)
  • limit (1-100, default 20)

Uses hybrid ranking: vector similarity + lexical matching + popularity boost.

Get Skill Detail

GET /api/v1/skills/:slug

Returns full detail for a single skill (public).

Get Skill File

GET /api/v1/skills/:slug/file?path=SKILL.md

Returns the raw file content for a skill. path defaults to SKILL.md.

Resolve Skill Dependencies

GET /api/v1/skills/:slug/resolve

Returns the resolved dependency tree for a skill (public).

Delete Skill (auth required)

DELETE /api/v1/skills/:slug
Authorization: Bearer sh_xxxxx

Soft-deletes a skill. Requires moderator or admin role.

Roles (continued)

Get Role Detail

GET /api/v1/roles/:slug

Returns full detail for a single role (public).

Get Role File

GET /api/v1/roles/:slug/file?path=ROLE.md

Returns the raw file content for a role. path defaults to ROLE.md.

Resolve Role Dependencies

GET /api/v1/roles/:slug/resolve

Returns the resolved dependency tree for a role (public).

Delete Role (auth required)

DELETE /api/v1/roles/:slug
Authorization: Bearer sh_xxxxx

Soft-deletes a role. Requires moderator or admin role.

Agents

List Agents

GET /api/v1/agents?limit=50&sort=updated

Query params:

  • limit (1-200, default 50)
  • sort (updated | downloads | stars)

Response shape matches List Skills.

Publish Agent (auth required)

POST /api/v1/agents
Content-Type: multipart/form-data

payload: { slug, displayName, version, changelog, customTags?, files[] }

File constraints: up to 100 files, 10 MB each, 50 MB total. Supports binary files.

Get Agent Detail

GET /api/v1/agents/:slug

Returns full detail for a single agent (public).

Get Agent File

GET /api/v1/agents/:slug/file?path=AGENT.md

Returns the raw file content for an agent. path defaults to AGENT.md.

Delete Agent (auth required)

DELETE /api/v1/agents/:slug
Authorization: Bearer sh_xxxxx

Soft-deletes an agent. Requires moderator or admin role.

Memories

List Memories

GET /api/v1/memories?limit=50&sort=updated

Query params:

  • limit (1-200, default 50)
  • sort (updated | downloads | stars)

Response shape matches List Skills.

Publish Memory (auth required)

POST /api/v1/memories
Content-Type: multipart/form-data

payload: { slug, displayName, version, changelog, customTags?, files[] }

File constraints: up to 100 files, 10 MB each, 50 MB total. Supports binary files.

Get Memory Detail

GET /api/v1/memories/:slug

Returns full detail for a single memory (public).

Get Memory File

GET /api/v1/memories/:slug/file?path=MEMORY.md

Returns the raw file content for a memory. path defaults to MEMORY.md.

Delete Memory (auth required)

DELETE /api/v1/memories/:slug
Authorization: Bearer sh_xxxxx

Soft-deletes a memory. Requires moderator or admin role.

Integrations

List Integrations

GET /api/v1/integrations?limit=50&sort=updated

Query params:

  • limit (1-200, default 50)
  • sort (updated | downloads | stars)

Response shape matches List Skills.

Publish Integration (auth required)

POST /api/v1/integrations
Content-Type: multipart/form-data

payload: { slug, displayName, version, changelog, customTags?, files[] }

File constraints: up to 100 files, 10 MB each, 50 MB total. Supports binary files.

Get Integration Detail

GET /api/v1/integrations/:slug

Returns full detail for a single integration (public).

Get Integration File

GET /api/v1/integrations/:slug/file?path=INTEGRATION.md

Returns the raw file content for an integration. path defaults to INTEGRATION.md.

Delete Integration (auth required)

DELETE /api/v1/integrations/:slug
Authorization: Bearer sh_xxxxx

Soft-deletes an integration. Requires moderator or admin role.

Stars

Toggle Star (auth required)

POST /api/v1/stars/toggle
Authorization: Bearer sh_xxxxx
Content-Type: application/json

{ "slug": "git-workflow", "kind": "skill|role|agent|memory|integration" }

Toggles the star status for the authenticated user. Returns { "starred": true } or { "starred": false }.

Downloads

Track Download

POST /api/v1/downloads
Content-Type: application/json

{ "kind": "skill|role|agent|memory|integration", "slug": "...", "version": "..." }

No auth required — download tracking is public (like npm). The version field is optional. Downloads are tracked via event sourcing: events are inserted into statEvents and flushed into target stats every 15 minutes by a cron job.

Auth

Whoami

GET /api/v1/whoami
Authorization: Bearer sh_xxxxx

Returns current user info: { handle, displayName, email, role, image }.

Admin

Set User Role (auth required, admin only)

POST /api/v1/admin/set-role
Authorization: Bearer sh_xxxxx
Content-Type: application/json

{ "handle": "someuser", "role": "moderator" }

Sets a user's role. Valid roles: admin, moderator, user.

Ban / Unban User (auth required, admin only)

POST /api/v1/admin/ban-user
Authorization: Bearer sh_xxxxx
Content-Type: application/json

{ "handle": "baduser", "blocked": true, "reason": "spam" }

Blocks or unblocks a user. The reason field is optional and only used when blocking.