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

# Partner API

> Llama a la Partner API v1 de RoofKit desde tu servidor con una API key del workspace.

Usa la Partner API cuando un sistema externo necesite acceso server-to-server autenticado y limitado a un workspace de RoofKit. CRMs, formularios, agendas y agencias la usan para sincronizar contactos, leer atribución, pedir reportes de techo y crear renders de techo.

Los clientes de IA que actúan por un miembro del workspace con sesión iniciada usan [RoofKit MCP](https://docs.roofkit.ai/es/mcp-server.md). MCP usa OAuth, no API keys.

## URL base y autenticación

Cada endpoint está bajo `https://api.roofkit.ai/api/v1`. Envía una API key del workspace como token Bearer en cada solicitud.

```bash Verificar la API key theme={null}
curl https://api.roofkit.ai/api/v1/me \
  -H "Authorization: Bearer rk_live_your_api_key"
```

[Verificar API key](https://docs.roofkit.ai/es/api-reference/foundation/verify-api-key.md) devuelve la key y el workspace al que pertenece.

> [card] [API keys](https://app.roofkit.ai/settings/api-keys)
>
> Crea y administra keys en la configuración del workspace. Mantén las keys en tu servidor y rótalas cuando cambie el responsable.

> [card] [Documento OpenAPI](https://api.roofkit.ai/api/v1/openapi.json)
>
> Descarga el contrato OpenAPI 3.1 con el que se construye esta referencia.

## Contrato

RoofKit Partner API v1 autentica solicitudes con API keys del workspace. Las API keys vinculan cada solicitud exactamente a un workspace; las rutas de Partner API no aceptan roofer\_id, workspace\_id ni identificadores de tenant. Los endpoints autenticados están limitados a 60 solicitudes por minuto por API key, método y plantilla de ruta; los intentos de autenticación inválidos se limitan por separado a 20 solicitudes por minuto por cliente y endpoint. Los parámetros y campos de fecha/hora aceptan ISO 8601 con Z o un desfase ±HH:MM, por ejemplo 2026-09-07T04:00:00Z o 2026-09-07T00:00:00-04:00. Ambos indican el mismo instante y devuelven el mismo resultado. Codifica + como %2B en una query string. Las respuestas usan UTC.

Una fecha/hora sin desfase, por ejemplo 2026-09-07T04:00:00, está obsoleta. Hasta la fecha de retiro, 2027-01-10T00:00:00Z, se interpreta como UTC, y la respuesta incluye un header `Deprecation` (RFC 9745) y un header `Sunset` (RFC 8594). A partir de la fecha de retiro, se requiere Z o un desfase ±HH:MM. Desde entonces, una fecha/hora sin desfase devuelve 400 con el código `VALIDATION_ERROR`, y la respuesta no incluye ningún header `Deprecation` ni `Sunset`.

Cada API key tiene solo los scopes que un propietario o administrador del workspace eligió al crear la key, y sus scopes nunca cambian. Cada operación indica los scopes que requiere en `x-required-scopes`. Una key nueva en Configuración empieza con el nivel predefinido Solo lectura: `leads.read`, `analytics.read`, `reports.read` y `data_objects.read`. Una key de Solo lectura puede llamar a todas las operaciones de lectura excepto las exportaciones, las lecturas de Sales Visualizer y los Data Objects en papelera, y no puede llamar a ninguna operación de escritura. Una llamada que necesita un scope que la key no tiene devuelve 403 `FORBIDDEN`, y `error.details.required_scope` indica un scope faltante.

## Errores

Cada error devuelve el mismo cuerpo. `code` es estable. Usa `request_id` cuando contactes a soporte.

```json Cuerpo de error theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request payload, query, or required header is invalid.",
    "request_id": "6f1c2a9e-4b7d-4c1e-9a53-2d8e0f7b3c41"
  }
}
```

| Código | Estado | Significado |
| - | - | - |
| `UNAUTHORIZED` | 401 | La API key falta, no es válida o fue revocada. |
| `FORBIDDEN` | 403 | La key no tiene un scope que el endpoint necesita. `details.required_scope` lo nombra. |
| `NOT_FOUND` | 404 | El recurso no existe en el workspace de la key. |
| `CONFLICT` | 409, 410 | La solicitud entra en conflicto con una idempotency key o con la identidad de un evento externo, o el recurso ya no existe. |
| `VALIDATION_ERROR` | 400, 411, 413 | El payload, un parámetro de query o un header requerido no es válido. |
| `INSUFFICIENT_CREDITS` | 402 | El workspace no tiene los créditos que usa la operación. |
| `RATE_LIMITED` | 429 | Espera el tiempo de `Retry-After` y envía la solicitud otra vez. |
| `INTERNAL_ERROR` | 500, 503 | RoofKit no pudo terminar la solicitud. Reinténtala más tarde con el mismo `Idempotency-Key`. |

`details` es opcional. Cada página de endpoint lista los estados que devuelve.

## Paginación

Los endpoints de lista con cursor reciben `limit` y `cursor`, y devuelven un objeto `pagination` con `limit`, `next_cursor` y `has_more`. Envía `next_cursor` como `cursor` para leer la página siguiente. Detente cuando `has_more` sea `false`. Cada página de endpoint muestra sus propios límites.

## Pruébalo

Cada página de endpoint tiene un playground. Envía la solicitud desde tu navegador directo a `api.roofkit.ai`, así tu API key no pasa por el host de la documentación.

> [!WARNING]
>
> **Las solicitudes cambian datos reales**
>
> El playground llama a la API en vivo con tu key. Los endpoints de escritura crean, actualizan y cobran en tu workspace. Usa una key de un workspace de prueba cuando pruebes endpoints de escritura.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.