# Mevak REST API v1

# Mevak REST API v1

Authenticate every request with your API key in the **`X-API-Key`** header:

```
X-API-Key: <your_api_key>
```

Get a key in **Settings → Developer → API Keys**. Base URL: `https://mevak.in`.

**Conventions**
- **Errors** return `{"error": {"code", "message", "details"}}` with a matching HTTP status. (Authentication failures — missing/invalid key — use FastAPI's `{"detail": "..."}` shape with 401.)
- **Pagination**: list endpoints take `?limit=` (1–100) and `?cursor=`; responses are `{"items": [...], "next_cursor": "..."|null}`. Pass `next_cursor` back as `?cursor=`.
- **Idempotency**: send an `Idempotency-Key` header on POST creates to safely retry — a repeat returns the original resource instead of creating a duplicate.


## Actions

### POST /api/v1/actions
Create an action

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required): 

### GET /api/v1/actions
List actions

Parameters:
- `deal_id` (query): 
- `status` (query): 
- `limit` (query): 
- `cursor` (query): 
- `x-api-key` (header) (required): 

### PATCH /api/v1/actions/{action_id}
Update an action

Parameters:
- `action_id` (path) (required): 
- `x-api-key` (header) (required): 

### GET /api/v1/actions/{action_id}
Get an action by ID

Parameters:
- `action_id` (path) (required): 
- `x-api-key` (header) (required): 

### POST /api/v1/actions/{action_id}/complete
Complete an action

Parameters:
- `action_id` (path) (required): 
- `x-api-key` (header) (required): 

## Companies

### POST /api/v1/companies
Create a company

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required): 

### GET /api/v1/companies
List companies

Parameters:
- `limit` (query): 
- `cursor` (query): 
- `search` (query): 
- `x-api-key` (header) (required): 

### GET /api/v1/companies/{company_id}
Get a company by ID

Parameters:
- `company_id` (path) (required): 
- `x-api-key` (header) (required): 

## Contacts

### POST /api/v1/contacts
Create a contact

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required): 

### GET /api/v1/contacts
List contacts

Parameters:
- `limit` (query): 
- `cursor` (query): 
- `search` (query): 
- `x-api-key` (header) (required): 

### GET /api/v1/contacts/{contact_id}
Get a contact by ID

Parameters:
- `contact_id` (path) (required): 
- `x-api-key` (header) (required): 

## Contracts

### GET /api/v1/contract-templates
List contract templates

Parameters:
- `x-api-key` (header) (required): 

### POST /api/v1/contracts
Create a contract from a template

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required): 

### GET /api/v1/contracts
List contracts

Parameters:
- `limit` (query): 
- `cursor` (query): 
- `status` (query): 
- `x-api-key` (header) (required): 

### GET /api/v1/contracts/{contract_id}
Get a contract by ID

Parameters:
- `contract_id` (path) (required): 
- `x-api-key` (header) (required): 

## Deals

### POST /api/v1/deals
Create a deal

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required): 

### GET /api/v1/deals
List deals

Parameters:
- `limit` (query): 
- `cursor` (query): 
- `stage` (query): 
- `search` (query): 
- `x-api-key` (header) (required): 

### GET /api/v1/deals/{deal_id}
Get a deal by ID

Parameters:
- `deal_id` (path) (required): 
- `x-api-key` (header) (required): 

### POST /api/v1/deals/{deal_id}/contacts
Link a contact to a deal

Parameters:
- `deal_id` (path) (required): 
- `x-api-key` (header) (required): 

## Notes

### POST /api/v1/notes
Add a note to a deal

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required): 

### GET /api/v1/notes
List notes for a deal

Parameters:
- `deal_id` (query): 
- `limit` (query): 
- `cursor` (query): 
- `x-api-key` (header) (required): 

## Reference

### GET /api/v1/deal-stages
List deal stages

Parameters:
- `pipeline_id` (query): Filter by pipeline UUID
- `x-api-key` (header) (required): 

### GET /api/v1/members
List members

Parameters:
- `x-api-key` (header) (required): 

### GET /api/v1/pipelines
List pipelines

Parameters:
- `x-api-key` (header) (required): 

### GET /api/v1/workspaces
List workspaces

Parameters:
- `x-api-key` (header) (required): 

## System

### GET /api/v1/ping
Health check

Parameters:
- `x-api-key` (header) (required): 

## Transcripts

### POST /api/v1/transcripts
Submit a meeting transcript

Parameters:
- `Idempotency-Key` (header): 
- `x-api-key` (header) (required):