{"openapi":"3.1.0","info":{"title":"Micro CRM API","description":"The Micro CRM API allows you to integrate your applications with Micro CRM.\nUse it to create clients from lead capture forms, sync deals from other systems,\nor build custom integrations.\n\n## Authentication\n\nAll API requests require authentication using an API key. Include your API key\nin the `Authorization` header:\n\n```\nAuthorization: Bearer mcrm_your_api_key_here\n```\n\nYou can create API keys in [Settings → API Keys](/settings).\n\n## Rate Limits\n\n- 100 requests per minute per API key\n- Rate limit headers are included in all responses\n\n## Errors\n\nThe API uses standard HTTP status codes:\n- `200` - Success\n- `201` - Created\n- `400` - Bad Request (invalid parameters)\n- `401` - Unauthorized (missing or invalid API key)\n- `403` - Forbidden (insufficient permissions)\n- `404` - Not Found\n- `409` - Conflict (e.g., duplicate email)\n- `429` - Too Many Requests (rate limited)\n- `500` - Internal Server Error","version":"1.0.0","contact":{"name":"PickleLlama Studio","url":"https://picklellama.studio"}},"servers":[{"url":"https://microcrm.picklellama.studio/api/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local Development"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Clients","description":"Manage clients/contacts in your CRM"},{"name":"Deals","description":"Manage deals in your sales pipeline"}],"paths":{"/clients":{"get":{"tags":["Clients"],"summary":"List clients","description":"Retrieve a paginated list of clients in your organization.","operationId":"listClients","parameters":[{"name":"limit","in":"query","description":"Maximum number of clients to return (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Number of clients to skip for pagination","schema":{"type":"integer","minimum":0,"default":0}},{"name":"search","in":"query","description":"Search clients by name, email, or company","schema":{"type":"string"}}],"responses":{"200":{"description":"List of clients","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Client"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"data":[{"id":"clx1234567890","name":"John Doe","email":"john@example.com","phone":"+1 555-0123","company":"Acme Inc","notes":"Met at conference","createdAt":"2024-01-15T10:30:00Z","updatedAt":"2024-01-15T10:30:00Z"}],"pagination":{"total":42,"limit":50,"offset":0,"hasMore":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Clients"],"summary":"Create a client","description":"Create a new client in your CRM. This is ideal for lead capture forms on your website.\n\n**Required permission:** `clients:write`","operationId":"createClient","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClientRequest"},"example":{"name":"Jane Smith","email":"jane@example.com","phone":"+1 555-0456","company":"Tech Corp","notes":"Interested in premium plan"}}}},"responses":{"201":{"description":"Client created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Client"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Client with this email already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"A client with this email already exists"},"existingId":{"type":"string","example":"clx1234567890"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/deals":{"get":{"tags":["Deals"],"summary":"List deals","description":"Retrieve a paginated list of deals in your pipeline.","operationId":"listDeals","parameters":[{"name":"limit","in":"query","description":"Maximum number of deals to return (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Number of deals to skip for pagination","schema":{"type":"integer","minimum":0,"default":0}},{"name":"stage","in":"query","description":"Filter by deal stage","schema":{"type":"string","enum":["LEAD","QUALIFIED","PROPOSAL","NEGOTIATION","WON","LOST"]}},{"name":"clientId","in":"query","description":"Filter by client ID","schema":{"type":"string"}}],"responses":{"200":{"description":"List of deals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Deals"],"summary":"Create a deal","description":"Create a new deal in your pipeline. The deal must be associated with an existing client.\n\n**Required permission:** `deals:write`","operationId":"createDeal","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDealRequest"},"example":{"title":"Website Redesign Project","clientId":"clx1234567890","value":5000,"stage":"QUALIFIED","notes":"Client wants modern design","expectedClose":"2024-03-15"}}}},"responses":{"201":{"description":"Deal created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deal"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Client not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Create keys in Settings → API Keys."}},"schemas":{"Client":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier","example":"clx1234567890"},"name":{"type":"string","description":"Client name","example":"John Doe"},"email":{"type":"string","format":"email","nullable":true,"description":"Email address","example":"john@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number","example":"+1 555-0123"},"company":{"type":"string","nullable":true,"description":"Company name","example":"Acme Inc"},"notes":{"type":"string","nullable":true,"description":"Additional notes","example":"Met at conference"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","name","createdAt","updatedAt"]},"CreateClientRequest":{"type":"object","properties":{"name":{"type":"string","description":"Client name (required)","example":"Jane Smith"},"email":{"type":"string","format":"email","description":"Email address","example":"jane@example.com"},"phone":{"type":"string","description":"Phone number","example":"+1 555-0456"},"company":{"type":"string","description":"Company name","example":"Tech Corp"},"notes":{"type":"string","description":"Additional notes","example":"Interested in premium plan"}},"required":["name"]},"Deal":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier","example":"clx0987654321"},"title":{"type":"string","description":"Deal title","example":"Website Redesign"},"value":{"type":"number","description":"Deal value in dollars","example":5000},"stage":{"type":"string","enum":["LEAD","QUALIFIED","PROPOSAL","NEGOTIATION","WON","LOST"],"description":"Current pipeline stage","example":"QUALIFIED"},"probability":{"type":"integer","minimum":0,"maximum":100,"description":"Win probability percentage","example":30},"notes":{"type":"string","nullable":true,"description":"Additional notes"},"expectedClose":{"type":"string","format":"date-time","nullable":true,"description":"Expected close date"},"closedAt":{"type":"string","format":"date-time","nullable":true,"description":"Actual close date (for won/lost deals)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"},"client":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","nullable":true}},"description":"Associated client"}},"required":["id","title","value","stage","probability","createdAt","updatedAt","client"]},"CreateDealRequest":{"type":"object","properties":{"title":{"type":"string","description":"Deal title (required)","example":"Website Redesign Project"},"clientId":{"type":"string","description":"Client ID (required)","example":"clx1234567890"},"value":{"type":"number","description":"Deal value in dollars","default":0,"example":5000},"stage":{"type":"string","enum":["LEAD","QUALIFIED","PROPOSAL","NEGOTIATION","WON","LOST"],"description":"Pipeline stage","default":"LEAD","example":"QUALIFIED"},"probability":{"type":"integer","minimum":0,"maximum":100,"description":"Win probability (auto-set based on stage if not provided)"},"notes":{"type":"string","description":"Additional notes"},"expectedClose":{"type":"string","format":"date","description":"Expected close date (YYYY-MM-DD)","example":"2024-03-15"}},"required":["title","clientId"]},"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items"},"limit":{"type":"integer","description":"Items per page"},"offset":{"type":"integer","description":"Current offset"},"hasMore":{"type":"boolean","description":"Whether more items exist"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}},"required":["error"]}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Name is required"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or missing API key. Include Authorization: Bearer <api_key>"}}}},"Forbidden":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Missing required permission: clients:write"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Request limit per minute"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when the rate limit resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded. Please try again later."}}}}}}}