Quickstart - Folkyn API

Overview

The Folkyn API (/api/v1) is for server-side integrations. Each request uses a team API key; all data is scoped to that team. Rate limit: 60 requests/minute per key by default — see Rate limits. Individual keys may have a higher limit; check X-RateLimit-Limit on responses.

What your API key represents

An API key is a team-level service account with access equivalent to a team administrator for every operation documented under /api/v1.

One key, one team — all requests are scoped to that team’s data.
Not a personal login — the key does not impersonate the user who created it; it is a machine identity for integrations.
Contract of record — the authoritative list of routes, fields, and behavior is the OpenAPI specification: https://api.folkyn.com/api/v1/openapi.yaml (JSON: openapi.json).

Accessible via the API

Area	Operations
Project codes	List, create, retrieve, update
Team tags	List, create, retrieve, update
Organizational teams	List, create, retrieve, update
Missions	List, create, retrieve, update, terminate
Freelancers	List, invite, retrieve, update
Team users	List, invite, retrieve, update
Activity reports	List, retrieve
Accounting	List entries, mark as paid

Not accessible via the API

Area	Notes
Mission signing and document workflows	Handled in the Folkyn app, not exposed on `/api/v1`
Freelancer KYC and document verification	Not available through the partner API
Team workflow and visibility settings	Configuration remains in the app
Browser session features	The API is server-to-server only (no end-user session)
Per-member visibility restrictions	The key can access all team data returned by documented routes; restricted views that apply to some team members in the app do not apply to API keys

Use the API Reference tab and the OpenAPI file above for the exact request and response shapes.

Prerequisites

A team API key from Settings → Developer in the Folkyn app (see Authentication).

Base URL

Production: https://api.folkyn.com For local testing, use the base URL of the environment you control (for example http://localhost:3000).

OpenAPI specification

Download the contract without an API key:

Format	URL
OpenAPI 3 (YAML)	`GET https://api.folkyn.com/api/v1/openapi.yaml`
OpenAPI 3 (JSON)	`GET https://api.folkyn.com/api/v1/openapi.json`

The API Reference tab on this site is generated from the same OpenAPI documents. Import either URL into Postman (Import → Link), Insomnia (Import Data → From URL), or your codegen tool; prefer JSON if YAML import fails.

First request

List project codes with the Authorization header:

curl -sS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.folkyn.com/api/v1/project-codes?page=1&per_page=10"

See Authentication if you need X-Api-Key instead of Bearer.

Success response

JSON responses wrap payloads in data:

{
  "data": {
    "items": [],
    "page": 1,
    "per_page": 10,
    "total": 0
  }
}

Errors

On failure, the body includes an error object; error.code is always the same integer as the HTTP status. See Errors for the full shape and common cases.

Next steps

Authentication — headers, key handling
Errors — error shape and codes
Rate limits — default 60 requests/minute per key; see X-RateLimit-Limit for your key’s limit

Use API Reference in the sidebar for every operation, schema, and generated cURL (and other) samples.

Product documentation

Broader Folkyn product help: doc.folkyn.com (linked from the app).

​Overview

​What your API key represents

​Accessible via the API

​Not accessible via the API

​Prerequisites

​Base URL

​OpenAPI specification

​First request

​Success response

​Errors

​Next steps

​Product documentation