> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/connectors/mayday.md).

# Mayday

K-AI ingests published Articles from a [Mayday](https://www.mayday.fr/) knowledge base via Mayday's public REST API (`https://public-api.mayday.fr`). The connector authenticates with an OAuth 2.0 client, lists the Articles of one knowledge in one locale, converts each Article body to Markdown, and pulls the images and file attachments embedded in it. The typical use case is making a Mayday help center — customer self-service, internal support, agent knowledge — searchable through K-AI MCP, with Mayday remaining the system of record.

Each K-AI source targets **one knowledge in one locale**. Register one source per locale you want indexed.

## Supported source versions

* **Mayday cloud** — the hosted product, through the public API at `public-api.mayday.fr`. On-prem or custom deployments are supported when reachable from the K-AI Instance and the `base_url` is set accordingly.
* **Articles only** — the connector ingests published content of type `Article`. Diagnostics, Steps, and External Content are not ingested. Raise the requirement with the K-AI integration team if you need them.
* **One knowledge per source** — a source is scoped to a single knowledge and locale (optionally narrowed to one collection subtree). To ingest several knowledges or locales, register one source each.

## Authentication

The connector uses the **OAuth 2.0 client-credentials grant**. It exchanges a `client_id` / `client_secret` pair for a bearer token at `POST /auth/oauth2/token`, then calls the API as `Authorization: Bearer <token>`. Tokens are cached and refreshed automatically.

Obtain the credentials from Mayday: create an API client in your Mayday workspace (or request one from Mayday support) and record its `client_id` and `client_secret`. The client's visibility determines what the connector can read — see [ACL handling](#acl-handling).

## Configuration

**Credential** — the secret pair stored once and reused across sources of the same workspace:

| Field           | Type   | Required | Description                                                                                                                                     |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`     | string | yes      | OAuth client identifier issued by Mayday.                                                                                                       |
| `client_secret` | string | yes      | OAuth client secret. Encrypted at rest by the platform.                                                                                         |
| `knowledge_id`  | string | yes      | The 24-character identifier of the target knowledge. Discovered by the portal (see below); it must match the knowledge referenced in the scope. |
| `base_url`      | string | no       | API base URL. Defaults to `https://public-api.mayday.fr`; override only for a non-standard deployment. Must be a full `https://` URL.           |

**Scope** — which slice of the knowledge to ingest, expressed as a path:

```
knowledge:<knowledge_id>/locale:<locale>[/collection:<collection_id>]
```

* `knowledge` — required; the 24-character knowledge identifier (matches the credential's `knowledge_id`).
* `locale` — required; one of Mayday's supported locales, e.g. `fr-fr` or `nl-nl`. The locale **filters every read**, so one source indexes exactly one language. `default` is not accepted.
* `collection` — optional; restrict ingestion to one collection and all of its descendant collections. Omit it to ingest the whole knowledge.

The K-AI admin portal fills these in for you: after entering the credential it lists the available knowledges (with their supported locales), and once a knowledge and locale are chosen it lists the collection tree. You do not have to assemble the path by hand.

**Advanced per-source options** — optional; sensible defaults apply:

| Option               | Type            | Default | Description                                                                                                                                         |
| -------------------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ingest_attachments` | boolean         | `true`  | Whether to ingest file attachments found in Article bodies. Turning it off on an existing source deletes the attachment documents already ingested. |
| `page_size`          | integer (1–100) | `100`   | Listing page size. Lower it only if a knowledge returns pages large enough to time out.                                                             |

## Document types ingested

* **Articles** — the Article body is converted from Mayday's rich-text format to **Markdown** (`text/markdown`). Inline images are embedded directly in the Markdown as data URIs, so an Article is self-contained.
* **Attachments** — files linked from an Article body are ingested as separate documents when `ingest_attachments` is on. Only web-safe document types are pulled: PDF, Word (`doc`, `docx`, `odt`), spreadsheets (`csv`, `ods`, `xls`, `xlsx`), presentations (`ppt`, `pps`, `odp`, `pptx`), and plain text (`txt`). Rich Text (`rtf`) is excluded. Each attachment is capped at 50 MiB.
* **Metadata** — each document carries its collection path, content labels, an "outdated" flag when Mayday marks the Article stale, and a human `mayday_url` back to the Article in the Mayday app. These map to the K-AI document's structural metadata.

## Sync mode

Mayday does not expose a change feed, so **every sync is a full crawl** of the scoped knowledge/locale. The connector paginates through the Article listing (page size up to 100), sorted on a stable creation key so pagination is consistent across pages.

Update detection is based on Mayday's content-update timestamp: an Article is re-downloaded only when its content actually changed, not when an unrelated bulk operation touches the corpus. Attachments are immutable — their filename carries a content hash — and are re-fetched only when the reference changes.

Deletions, unpublishes, and collection moves have no native tombstone in the API. They are detected by an **orphan scan** after each full crawl: any document not seen in the current crawl is dropped on the K-AI side. A completeness guard aborts the orphan scan if the crawl walked materially fewer Articles than Mayday reports as the total, so a partial or interrupted crawl can never trigger a mass deletion — the cycle is retried instead.

## Locales & multi-language

Mayday content is per-locale: the same Article returns a different translated body under each locale, and collections themselves are translated. Because the locale filters every read:

* One K-AI source indexes exactly one locale.
* The same Article ingested under two locales becomes **two K-AI documents** — this is intentional, so retrieval can return the reader's language.
* To cover several languages, register one source per locale against the same knowledge.

## ACL handling

Mayday's public API does not expose per-Article access rules, so the connector does **not** propagate a native ACL. What a source can read is bounded entirely by the visibility of its OAuth client in Mayday.

Apply the **mapped** ACL strategy, as with [ServiceNow](/knowledge-ai/sources-and-ingestion/connectors/servicenow.md): attach a K-AI group rule at source registration, and every document ingested from the source inherits that group. For finer-grained control, scope sources to separate collections (or separate API clients) by audience and assign distinct group rules. At retrieval time, [K-AI MCP](/knowledge-ai/k-ai-mcp/mcp.md) replays the mapped ACL against the calling identity.

## Rate limits & throttling

Mayday enforces **200 API requests per minute per client**. The API returns no rate-limit headers and no `Retry-After` on a `429`, so the connector responds to a `429` with exponential back-off and jitter and reschedules the crawl. API calls are concurrency-capped so a single crawl stays within the quota.

Image and attachment downloads are served from Mayday's blob storage, **not** counted against the 200/min API quota; they run on a separate, higher concurrency budget.

## Known limitations

* **Articles only** — Diagnostics, Steps, and External Content are not ingested.
* **No native ACL** — access on the K-AI side is group-rule based, not replicated from Mayday.
* **Full crawl only** — there is no incremental/delta sync; each cycle re-enumerates the scoped content (change detection still avoids re-downloading unchanged bodies).
* **One locale per source** — multi-language coverage requires one source per locale.
* **Attachments come from Article bodies** — files not referenced in an Article body are not discovered, and only the allow-listed document types are pulled.
* **`default` locale unsupported** — it returns no rows; always pick a concrete locale.

## Setup walkthrough

1. **Create a Mayday API client** in your Mayday workspace and record its `client_id` and `client_secret`.
2. **Add the credential in the K-AI admin portal**: select Mayday and enter the `client_id` and `client_secret`. Leave `base_url` at its default unless you run a non-standard deployment.
3. **Pick the scope** — the portal lists the available knowledges; choose one, choose a locale, and optionally narrow to a collection. This builds the `knowledge:.../locale:...[/collection:...]` scope for you.
4. **Assign a group rule** for ACL mapping — every document ingested from this source inherits that group on the K-AI side.
5. **Set the sync schedule** and **trigger a test sync**.
6. **Confirm the document count** in the indexing statistics of the instance page in the K-AI Studio portal.