> ## Documentation Index
> Fetch the complete documentation index at: https://doc.folkyn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Folkyn team API — base URL, OpenAPI, and your first authenticated request

## 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](/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](https://api.folkyn.com/api/v1/openapi.yaml)** (JSON: [openapi.json](https://api.folkyn.com/api/v1/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](/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:

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

See [Authentication](/authentication) if you need **`X-Api-Key`** instead of **Bearer**.

## Success response

JSON responses wrap payloads in **`data`**:

```json theme={null}
{
  "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](/errors) for the full shape and common cases.

## Next steps

* [Authentication](/authentication) — headers, key handling
* [Errors](/errors) — error shape and codes
* [Rate limits](/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](https://doc.folkyn.com/)** (linked from the app).