01 / Developers
A REST API over your portfolio. Mint a key in your workspace, then read your profile, outcomes, posts, pages, and more as clean JSON. Grant the key the write scope and the same API creates, updates, and deletes content for you.
Everything is versioned under /api/v1, scoped to your tenant, and documented by a live OpenAPI 3.1 spec you can download below.
02 / Getting started
01
Open your workspace at /admin and go to Settings > API. The workspace owner mints a key there. The raw key is shown once, so copy it immediately.
02
Send the key as a bearer token on every request: Authorization: Bearer pk_live_... . No cookies, no sessions, no OAuth dance.
03
Call /api/v1/portfolio to pull your entire published portfolio in one response, then narrow to a single resource as you need it.
curl https://portfolio.wrxstack.com/api/v1/portfolio \
-H "Authorization: Bearer pk_live_your_key_here"03 / Authentication
Every request authenticates with a single bearer token. Keys live entirely in your workspace, never expire on us, and only ever reach your own workspace. A key reads by default; writing needs the write scope, granted when you mint it.
How keys work
Stay secure
04 / MCP server
Folio hosts a Model Context Protocol server that exposes the v1 API as tools, so Claude, Cursor, VS Code, and other MCP clients can answer questions grounded in your real portfolio and, with a write-scoped key, edit it for you. There is nothing to install: point your client at one URL and send your API key.
Hosted, ready now
One URL. Your API key.
With Claude Code it is a single command. Every other client is below.
claude mcp add --transport http folio https://portfolio.wrxstack.com/api/mcp \
--header "Authorization: Bearer pk_live_your_key_here"What it does
Read everything
Fetch the entire portfolio in one call, list or read any resource (outcomes, posts, pages, experience, skills, stats, awards, education, testimonials, links), and resolve a single item by slug.
Write tools
Create, update, and delete outcomes, posts, pages, experience, skills, stats, awards, education, testimonials, and links, and update your profile, with folio_create_, folio_update_, and folio_delete_ tools. Writes need a write-scoped key.
Same key, same rules
Tools run through the same v1 endpoints, so the per-key rate limit, monthly quota, and write scope apply exactly as they do to direct requests. A read-only key gets a clear read-only message instead of mutating.
Folio hosts the MCP server. Point Claude, Cursor, VS Code, or any MCP client at one URL with your API key. Nothing to install.
Anthropic terminal agent. Connects to the hosted URL in one command.
Config location
claude mcp add --transport http folio https://portfolio.wrxstack.com/api/mcp \
--header "Authorization: Bearer pk_live_your_key_here"Steps
Verify
Run claude mcp list: folio should show as connected. In a session, /mcp lists the folio tools. Ask "Summarize my portfolio" to confirm.
05 / Endpoint reference
Reads are GET and work with any key. POST, PATCH, and DELETE need a key with the write scope. This table is generated from the live route registry, so it always matches what the API actually serves. Paginated routes accept limit and offset.
| Method | Path | Summary | Auth | Paginated |
|---|---|---|---|---|
| Portfolio | ||||
| GET | /api/v1/portfolio | Get the full published portfolio | Requires API keyKey | No |
| Profile | ||||
| GETPATCH | /api/v1/profile | Get the public profile | Requires API keyKey | No |
| Outcomes | ||||
| GETPOST | /api/v1/outcomes | List published outcomes | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/outcomes/{slug} | Get one outcome by slug | Requires API keyKey | No |
| Posts | ||||
| GETPOST | /api/v1/posts | List published blog posts | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/posts/{slug} | Get one blog post by slug | Requires API keyKey | No |
| Pages | ||||
| GETPOST | /api/v1/pages | List published custom pages | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/pages/{slug} | Get one custom page by slug | Requires API keyKey | No |
| Experience | ||||
| GETPOST | /api/v1/experience | List experience entries | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/experience/{id} | Get one experience entry by id | Requires API keyKey | No |
| Skills | ||||
| GETPOST | /api/v1/skills | List skills | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/skills/{id} | Get one skill by id | Requires API keyKey | No |
| Stats | ||||
| GETPOST | /api/v1/stats | List headline stats | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/stats/{id} | Get one stat by id | Requires API keyKey | No |
| Awards | ||||
| GETPOST | /api/v1/awards | List awards | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/awards/{id} | Get one award by id | Requires API keyKey | No |
| Education | ||||
| GETPOST | /api/v1/education | List education and certifications | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/education/{id} | Get one education entry by id | Requires API keyKey | No |
| Testimonials | ||||
| GETPOST | /api/v1/testimonials | List testimonials | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/testimonials/{id} | Get one testimonial by id | Requires API keyKey | No |
| Links | ||||
| GETPOST | /api/v1/links | List social and contact links | Requires API keyKey | Yes |
| GETPATCHDELETE | /api/v1/links/{id} | Get one link by id | Requires API keyKey | No |
| Meta | ||||
| GET | /api/v1/openapi.json | Download the OpenAPI 3.1 document (JSON) | Public, no key requiredPublic | No |
| GET | /api/v1/openapi.yaml | Download the OpenAPI 3.1 document (YAML) | Public, no key requiredPublic | No |
| GET | /api/v1/postman.json | Download a Postman v2.1 collection | Public, no key requiredPublic | No |
Paths shown with {slug} take a URL-safe identifier. Detail routes return 404 when the slug does not resolve.
06 / Conventions
Success response
Collections wrap items in a pagination block. Detail and singleton routes return the item directly under data.
{
"apiVersion": "v1",
"tenant": { "slug": "your-workspace", "name": "Your Name" },
"pagination": { "total": 12, "limit": 20, "offset": 0, "hasMore": false },
"data": [
{ "slug": "shipped-the-redesign", "title": "Shipped the redesign", "summary": "..." }
]
}Error response
Errors use a stable envelope with a machine-readable code and a human message. The HTTP status matches the code.
{
"error": {
"code": "unauthorized",
"message": "The provided API key is not valid."
}
}| Status | Code | When you see it |
|---|---|---|
| 400 | bad_request | A query parameter is malformed, e.g. a non-integer limit or offset. |
| 401 | unauthorized | No bearer token, or the key is unknown. A WWW-Authenticate challenge is returned. |
| 403 | forbidden | The key was revoked or expired, or a write was sent with a key that lacks the write scope. |
| 404 | not_found | No published portfolio for the tenant, or the requested slug does not exist. |
| 429 | rate_limited | The per-key window was exhausted. A Retry-After header tells you when to retry. |
| 500 | internal_error | An unexpected server error. Safe to retry with backoff. |
Pagination
Collection routes accept limit (1 to 100, default 20) and offset (a non-negative integer). The pagination block reports total, the echoed limit and offset, and hasMore so you know when to stop paging.
Rate limits
Each key gets 60 requests per 60 second window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (a Unix timestamp). On a 429 you also get a Retry-After header in seconds.
07 / Downloads
These documents are public, no key required, so you can wire up tooling before you mint a key.
08 / Build on Folio
Create a workspace, publish your portfolio, and generate an API key under Settings > API. Questions about scopes or limits? We are happy to help.