> ## 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. # Create Mission > Creates a mission for the API key's team. For `hourly`, `daily`, or `monthly`, send `rate_amount` > 0; for `deliverable`, send `deliverables` instead of `rate_amount`. Dates: **YYYY-MM-DD**. **Generate a services-agreement PDF** (`contract_type: services_agreement`, default) — `use_folkyn_template: true` + `team_signer_id`, then either: - **Default template:** `template_locale` = `fr` or `en`. - **Custom template:** `folkyn_template_id` = prestation template UUID. **Generate a master-agreement PDF** (`contract_type: master_agreement`): `master_agreement_template_id` + `master_agreement_valid_until` + `team_signer_id`. If the freelancer already has a framework agreement in progress or awaiting signature (same team, not expired), that agreement is **reused and linked** to the mission — no new PDF is generated and template fields are **ignored**. Send template fields only when no current framework agreement exists (e.g. first mission under master agreement, or previous agreement expired). For services agreements only, omit template fields to create a mission without a generated document. Master-agreement missions require either a reusable framework agreement or `master_agreement_template_id` / uploaded `master_agreement_file`. Optional: `purchase_order`, `project_code_id`, `approver_id`. The freelance referent is set on the freelancer profile (`PATCH /api/v1/freelancers/{id}`), not on mission create. ## OpenAPI ````yaml /openapi.yaml post /api/v1/missions openapi: 3.0.3 info: title: Folkyn API version: 1.0.0 license: name: Proprietary url: https://folkyn.com description: >- Team API key; responses in `data`, errors in `error` with `X-Request-Id`. Spec at `/api/v1/openapi.yaml` and `/api/v1/openapi.json` (no key). **60 requests/minute** per key on `/api/v1/*`. servers: - url: https://api.folkyn.com description: Production security: - bearerAuth: [] - ApiKeyHeader: [] tags: - name: Specification description: OpenAPI document download (no authentication) - name: Project codes description: Team project codes - name: Team tags description: Team tags - name: Teams description: Organizational teams (team units) and member lists - name: Missions description: Team missions - name: Freelancers description: Team freelancers and invitations - name: Activity reports description: Activity reports (CRA) - name: Accounting description: Accounting entries paths: /api/v1/missions: post: tags: - Missions summary: Create Mission description: > Creates a mission for the API key's team. For `hourly`, `daily`, or `monthly`, send `rate_amount` > 0; for `deliverable`, send `deliverables` instead of `rate_amount`. Dates: **YYYY-MM-DD**. **Generate a services-agreement PDF** (`contract_type: services_agreement`, default) — `use_folkyn_template: true` + `team_signer_id`, then either: - **Default template:** `template_locale` = `fr` or `en`. - **Custom template:** `folkyn_template_id` = prestation template UUID. **Generate a master-agreement PDF** (`contract_type: master_agreement`): `master_agreement_template_id` + `master_agreement_valid_until` + `team_signer_id`. If the freelancer already has a framework agreement in progress or awaiting signature (same team, not expired), that agreement is **reused and linked** to the mission — no new PDF is generated and template fields are **ignored**. Send template fields only when no current framework agreement exists (e.g. first mission under master agreement, or previous agreement expired). For services agreements only, omit template fields to create a mission without a generated document. Master-agreement missions require either a reusable framework agreement or `master_agreement_template_id` / uploaded `master_agreement_file`. Optional: `purchase_order`, `project_code_id`, `approver_id`. The freelance referent is set on the freelancer profile (`PATCH /api/v1/freelancers/{id}`), not on mission create. operationId: createMission requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MissionCreateRequest' examples: services_agreement_folkyn_locale: summary: Services agreement — Folkyn template by language value: name: Backend API — Q3 description: API development and maintenance for the Q3 release. mission_type: daily contract_type: services_agreement rate_amount: 650 start_date: '2026-07-01' end_date: '2026-12-31' freelancer_id: aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee team_signer_id: bbbbbbbb-cccc-4ddd-eeee-ffffffffffff use_folkyn_template: true template_locale: fr services_agreement_with_template: summary: Services agreement — team template UUID value: name: Backend API — Q3 description: API development and maintenance for the Q3 release. mission_type: daily contract_type: services_agreement rate_amount: 650 start_date: '2026-07-01' end_date: '2026-12-31' freelancer_id: aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee team_signer_id: bbbbbbbb-cccc-4ddd-eeee-ffffffffffff use_folkyn_template: true folkyn_template_id: cccccccc-dddd-4eee-ffff-000000000001 services_agreement_simple: summary: Services agreement — no generated document value: name: Backend API — Q3 description: API development and maintenance for the Q3 release. mission_type: daily contract_type: services_agreement rate_amount: 650 start_date: '2026-07-01' end_date: '2026-12-31' freelancer_id: aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee purchase_order: PO-2026-001 services_agreement_with_approver: summary: Services agreement — pending admin approval before freelancer value: name: Backend API — Q3 (review) description: API development and maintenance for the Q3 release. mission_type: daily contract_type: services_agreement rate_amount: 650 start_date: '2026-07-01' end_date: '2026-12-31' freelancer_id: aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee approver_id: bbbbbbbb-cccc-4ddd-eeee-ffffffffffff master_agreement: summary: Master agreement with Folkyn template value: name: Framework — Jane Doe description: Framework agreement for consulting services. mission_type: daily contract_type: master_agreement rate_amount: 600 start_date: '2026-07-01' end_date: '2026-12-31' freelancer_id: aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee team_signer_id: bbbbbbbb-cccc-4ddd-eeee-ffffffffffff master_agreement_template_id: cccccccc-dddd-4eee-ffff-000000000001 master_agreement_valid_until: '2027-06-30' responses: '201': description: Created — same object as GET /api/v1/missions/{id} content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/MissionDetail' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/PublicError' '401': $ref: '#/components/responses/Unauthorized' '403': description: Forbidden (e.g. subscription required) content: application/json: schema: $ref: '#/components/schemas/PublicError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: MissionCreateRequest: type: object required: - name - description - mission_type - start_date - end_date - freelancer_id properties: name: type: string description: type: string description: Mission objectives, deliverables, and working conditions. mission_type: $ref: '#/components/schemas/MissionBillingType' contract_type: type: string enum: - services_agreement - master_agreement default: services_agreement rate_amount: type: number description: >- Required for hourly, daily, and monthly missions (HT unit rate). Omit for deliverable missions. deliverables: type: array description: Required when mission_type is deliverable. items: type: object required: - name - quantity - amount_ht properties: name: type: string quantity: type: number amount_ht: type: number start_date: type: string format: date description: YYYY-MM-DD end_date: type: string format: date description: YYYY-MM-DD freelancer_id: type: string format: uuid description: Active freelancer profile UUID on the team. team_signer_id: type: string format: uuid description: >- Required when generating a contract from a template (`folkyn_template_id` or `master_agreement_template_id`). Active team member profile UUID as company signatory. purchase_order: type: string project_code_id: type: string format: uuid approver_id: type: string format: uuid description: Active team-admin UUID — mission stays in `draft` until approved. use_folkyn_template: type: boolean description: >- Set `true` to generate a services-agreement PDF from a DOCX template. template_locale: type: string enum: - fr - en description: >- Default prestation template language. Use instead of `folkyn_template_id` when you do not have the template UUID. folkyn_template_id: type: string format: uuid description: Prestation template UUID. Alternative to `template_locale`. master_agreement_template_id: type: string format: uuid description: >- Team DOCX template UUID (`master_agreement` only). Requires `team_signer_id` and `master_agreement_valid_until`. Ignored when the freelancer already has a current framework agreement (in progress or awaiting signature). master_agreement_valid_until: type: string format: date description: >- Framework agreement end date (YYYY-MM-DD). Required with `master_agreement_template_id`. Ignored when an existing framework agreement is reused. MissionDetail: $ref: '#/components/schemas/MissionListItemPublic' PublicError: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: integer description: Same as HTTP status; use `message` and `details` to narrow. enum: - 400 - 401 - 403 - 404 - 429 - 500 example: 401 message: type: string request_id: type: string format: uuid description: Correlates with the X-Request-Id response header. details: $ref: '#/components/schemas/PublicErrorDetails' MissionBillingType: type: string description: > Billing model for the mission (Postgres enum `mission_type`). `hourly` / `daily` / `monthly` use **`rate_amount`** as the price per that unit in **`currency`**. `deliverable` missions bill via the **deliverables catalog** (quantities and line amounts); `rate_amount` may still be set as a reference but line totals come from catalog rows on mission detail. enum: - hourly - daily - monthly - deliverable MissionListItemPublic: type: object properties: id: type: string format: uuid name: type: string description: type: string nullable: true mission_type: $ref: '#/components/schemas/MissionBillingType' contract_kind: type: string description: > Contract channel: **`master_agreement`** = framework agreement path, **`services_agreement`** = standalone services agreement. Only these two values are returned. enum: - master_agreement - services_agreement has_document: type: boolean currency: type: string description: >- ISO 4217 alphabetic code (e.g. `EUR`, `USD`) as stored on the mission. example: EUR rate_amount: type: number description: > Unit price in **`currency`** according to **`mission_type`**: per hour, per day, per month, or mission-level reference for deliverable missions (see `MissionBillingType`). Not a daily rate derived by dividing elsewhere — the unit is implied by `mission_type`. client_rate_amount: type: number nullable: true description: > ESN teams only: unit price excl. VAT billed to the end client for the same unit as **`rate_amount`** (per hour, day, or month per **`mission_type`**). Null for non-ESN teams, deliverable missions, or when unset. start_date: type: string format: date end_date: type: string format: date status: $ref: '#/components/schemas/MissionStatus' early_termination_date: type: string format: date nullable: true description: >- Effective end date chosen when the mission was terminated early (**YYYY-MM-DD**). Null if the mission was never terminated early. terminated_by: type: string format: uuid nullable: true description: >- UUID of the team user who terminated the mission early. Null if the mission was never terminated early. external_referent: type: object nullable: true allOf: - $ref: '#/components/schemas/ActivityReportExternalReferentPublic' purchase_order: type: string nullable: true external_id: type: string nullable: true description: >- External identifier for the mission set by the team (e.g. an ERP or third-party system reference); null if unset. project_code_id: type: string format: uuid nullable: true project_code: type: object nullable: true allOf: - $ref: '#/components/schemas/ActivityReportMissionProjectCodePublic' description: Primary linked project code; null if the mission has none. project_codes: type: array description: > All project codes linked to the mission (`id`, `name`, `external_id`). Populated on **`GET /api/v1/missions`** and **`GET /api/v1/missions/{id}`**. Empty when the mission has no linked codes. items: $ref: '#/components/schemas/ActivityReportMissionProjectCodePublic' deliverables_catalog: type: array description: > Mission deliverables catalog. Empty on **`GET /api/v1/missions`**; filled on **`GET /api/v1/missions/{id}`**. items: $ref: '#/components/schemas/MissionDeliverableCatalogItem' created_at: type: string format: date-time updated_at: type: string format: date-time created_by: type: object nullable: true allOf: - $ref: '#/components/schemas/PartnerPerson' freelancer: type: object nullable: true allOf: - $ref: '#/components/schemas/MissionFreelancerPublic' team_signer: type: object nullable: true allOf: - $ref: '#/components/schemas/PartnerPerson' PublicErrorDetails: type: object description: Optional structured hints (validation, scope, rate limit). additionalProperties: true properties: reason: $ref: '#/components/schemas/PartnerValidationErrorReason' field: type: string description: JSON body field name when applicable (e.g. `name`). example: name requiredScope: type: string description: >- Required OAuth-like scope string when `code` is 403 (insufficient scope). example: tags:write retryAfterSeconds: type: integer minimum: 0 description: Hint when `code` is 429. MissionStatus: type: string description: > Mission status. Derived from dates, pending documents, and pending addenda — the same value used for filtering (see the `status` query parameter). enum: - draft - pending-freelancer-review - pending-company-review - pending-freelancer-extension - in-progress - completed - early-terminated - cancelled - rejected - deleted ActivityReportExternalReferentPublic: type: object required: - id - email - company - siren - address - postal_code - city description: >- External client referent on the mission (id, email, company name, SIREN, address fields). Distinct from `freelancer.referent` (team referent). properties: id: type: string format: uuid nullable: true description: Client company UUID; null when unset. email: type: string company: type: string siren: type: string nullable: true pattern: ^[0-9]{9}$ description: >- Client company SIREN (9 digits, no spaces); null when unset or fewer than 9 digits. address: type: string nullable: true description: Street address line. postal_code: type: string nullable: true city: type: string nullable: true ActivityReportMissionProjectCodePublic: type: object required: - id - name - external_id properties: id: type: string format: uuid name: type: string external_id: type: string nullable: true description: Optional client / ERP reference for the project code. MissionDeliverableCatalogItem: type: object properties: id: type: string format: uuid name: type: string quantity: type: integer amount_excl_vat: type: number order_index: type: integer PartnerPerson: type: object properties: id: type: string format: uuid first_name: type: string last_name: type: string MissionFreelancerPublic: type: object description: > Assigned freelancer. `referent` is the team member assigned as referent for this freelancer, when configured — not the external client referent on the mission. properties: id: type: string format: uuid first_name: type: string last_name: type: string email: type: string referent: type: object nullable: true description: Team referent (id, name, email); null if none. allOf: - $ref: '#/components/schemas/PartnerFreelancerReferentPublic' PartnerValidationErrorReason: type: string description: >- Machine-readable validation subtype (HTTP 400) for create tag / project code. enum: - invalid_json - required_field - duplicate_name PartnerFreelancerReferentPublic: type: object description: Team referent (id, first name, last name, email). required: - id - first_name - last_name - email properties: id: type: string format: uuid first_name: type: string last_name: type: string email: type: string responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/PublicError' RateLimited: description: Too many requests content: application/json: schema: $ref: '#/components/schemas/PublicError' InternalError: description: Server error content: application/json: schema: $ref: '#/components/schemas/PublicError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Use `Authorization: Bearer `' ApiKeyHeader: type: apiKey in: header name: X-Api-Key ````