{
  "openapi": "3.0.3",
  "info": {
    "title": "JUXA.IO CRM — LLM & automation tool subset",
    "version": "1.0.0",
    "description": "Curated REST paths for AI assistants and iPaaS (JSON in/out). Excludes schema-shaping object mutations and admin-only routes. For the full API see /openapi.json. Chat message streaming (POST /api/v1/chat/completions) is not listed here because it returns text/event-stream — use MCP (@juxa/mcp-juxa-crm), the web app, or a thin backend that consumes SSE."
  },
  "servers": [
    {
      "url": "https://YOUR_JUXA_ORIGIN",
      "description": "Replace with your deployment origin (no trailing slash), e.g. https://app.example.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Workspace API key from Settings → API Keys (oc_sk_…). Scopes: integrations:read/write/assistant or * — see /llms-api.txt"
      }
    },
    "schemas": {
      "SortConfig": {
        "type": "object",
        "properties": {
          "attribute": {
            "type": "string",
            "description": "Attribute slug"
          },
          "direction": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ]
          }
        }
      },
      "FilterGroup": {
        "type": "object",
        "description": "Filter group with AND/OR logic",
        "properties": {
          "operator": {
            "type": "string",
            "enum": [
              "and",
              "or"
            ]
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "attribute": {
                  "type": "string",
                  "description": "Attribute slug"
                },
                "operator": {
                  "type": "string",
                  "enum": [
                    "equals",
                    "not_equals",
                    "contains",
                    "not_contains",
                    "starts_with",
                    "ends_with",
                    "is_empty",
                    "is_not_empty",
                    "gt",
                    "gte",
                    "lt",
                    "lte"
                  ]
                },
                "value": {
                  "description": "Filter value"
                }
              }
            }
          }
        }
      },
      "RecordValues": {
        "type": "object",
        "description": "Key-value pairs where keys are attribute slugs. Value format depends on attribute type.",
        "additionalProperties": true
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "Record": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "objectId": {
            "type": "string",
            "format": "uuid"
          },
          "values": {
            "$ref": "#/components/schemas/RecordValues"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Attribute": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "number",
              "currency",
              "date",
              "timestamp",
              "checkbox",
              "select",
              "status",
              "rating",
              "email_address",
              "phone_number",
              "domain",
              "location",
              "personal_name",
              "record_reference",
              "actor_reference",
              "interaction"
            ]
          },
          "config": {
            "type": "object"
          },
          "isRequired": {
            "type": "boolean"
          },
          "isUnique": {
            "type": "boolean"
          },
          "isMultiselect": {
            "type": "boolean"
          },
          "sortOrder": {
            "type": "integer"
          }
        }
      },
      "Object": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "singularName": {
            "type": "string"
          },
          "pluralName": {
            "type": "string"
          },
          "icon": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/objects": {
      "get": {
        "operationId": "listObjects",
        "summary": "List all objects",
        "tags": [
          "Objects"
        ],
        "responses": {
          "200": {
            "description": "List of objects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Object"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/objects/{slug}": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Object slug (e.g. people, companies, deals)"
        }
      ],
      "get": {
        "operationId": "getObject",
        "summary": "Get object with attributes",
        "tags": [
          "Objects"
        ],
        "responses": {
          "200": {
            "description": "Object with attributes"
          }
        }
      }
    },
    "/api/v1/objects/{slug}/attributes": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "listAttributes",
        "summary": "List attributes for object",
        "tags": [
          "Attributes"
        ],
        "responses": {
          "200": {
            "description": "List of attributes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Attribute"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/objects/{slug}/records": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "listRecords",
        "summary": "List records for object",
        "tags": [
          "Records"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "records": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Record"
                          }
                        },
                        "pagination": {
                          "$ref": "#/components/schemas/Pagination"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createRecord",
        "summary": "Create a record",
        "tags": [
          "Records"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "values"
                ],
                "properties": {
                  "values": {
                    "$ref": "#/components/schemas/RecordValues"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Record created"
          }
        }
      }
    },
    "/api/v1/objects/{slug}/records/{recordId}": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "recordId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getRecord",
        "summary": "Get a single record",
        "tags": [
          "Records"
        ],
        "responses": {
          "200": {
            "description": "Record with values"
          }
        }
      },
      "patch": {
        "operationId": "updateRecord",
        "summary": "Update record values",
        "tags": [
          "Records"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "values"
                ],
                "properties": {
                  "values": {
                    "$ref": "#/components/schemas/RecordValues"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated record"
          }
        }
      },
      "delete": {
        "operationId": "deleteRecord",
        "summary": "Delete a record",
        "tags": [
          "Records"
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/objects/{slug}/records/query": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "operationId": "queryRecords",
        "summary": "Query records with filters and sorting",
        "tags": [
          "Records"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "integer",
                    "default": 50,
                    "maximum": 200
                  },
                  "offset": {
                    "type": "integer",
                    "default": 0
                  },
                  "filter": {
                    "$ref": "#/components/schemas/FilterGroup"
                  },
                  "sorts": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/SortConfig"
                    }
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "assert"
                    ],
                    "description": "Assert mode: find-or-create a record"
                  },
                  "matchAttribute": {
                    "type": "string",
                    "description": "Attribute slug to match on (assert mode)"
                  },
                  "matchValue": {
                    "description": "Value to match (assert mode)"
                  },
                  "values": {
                    "$ref": "#/components/schemas/RecordValues"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Filtered records with pagination"
          }
        }
      }
    },
    "/api/v1/notes": {
      "get": {
        "operationId": "listNotes",
        "summary": "List all notes",
        "tags": [
          "Notes"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated notes"
          }
        }
      },
      "post": {
        "operationId": "createNote",
        "summary": "Create a note linked to a CRM record",
        "tags": [
          "Notes"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "recordId"
                ],
                "properties": {
                  "recordId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "title": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Note created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/notes/{noteId}": {
      "parameters": [
        {
          "name": "noteId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getNote",
        "summary": "Get a note",
        "tags": [
          "Notes"
        ],
        "responses": {
          "200": {
            "description": "Note object"
          }
        }
      },
      "patch": {
        "operationId": "updateNote",
        "summary": "Update a note",
        "tags": [
          "Notes"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated note"
          }
        }
      },
      "delete": {
        "operationId": "deleteNote",
        "summary": "Delete a note",
        "tags": [
          "Notes"
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/tasks": {
      "get": {
        "operationId": "listTasks",
        "summary": "List tasks",
        "tags": [
          "Tasks"
        ],
        "parameters": [
          {
            "name": "showCompleted",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated tasks"
          }
        }
      },
      "post": {
        "operationId": "createTask",
        "summary": "Create a task",
        "tags": [
          "Tasks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "content"
                ],
                "properties": {
                  "content": {
                    "type": "string"
                  },
                  "deadline": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "recordIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "assigneeIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Task created"
          }
        }
      }
    },
    "/api/v1/tasks/{taskId}": {
      "parameters": [
        {
          "name": "taskId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "patch": {
        "operationId": "updateTask",
        "summary": "Update a task",
        "tags": [
          "Tasks"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": {
                    "type": "string"
                  },
                  "isCompleted": {
                    "type": "boolean"
                  },
                  "deadline": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated task"
          }
        }
      },
      "delete": {
        "operationId": "deleteTask",
        "summary": "Delete a task",
        "tags": [
          "Tasks"
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    },
    "/api/v1/workspace": {
      "get": {
        "operationId": "getWorkspace",
        "summary": "Get current workspace",
        "tags": [
          "Workspace"
        ],
        "responses": {
          "200": {
            "description": "Workspace object"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Global search across all records",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results"
          }
        }
      }
    },
    "/api/v1/records/browse": {
      "get": {
        "operationId": "browseRecords",
        "summary": "Browse recent records across all objects",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent records with display info"
          }
        }
      }
    },
    "/api/v1/chat/conversations": {
      "get": {
        "operationId": "listChatConversations",
        "summary": "List AI chat conversations for the authenticated user",
        "description": "Optional query `surface` (default crm_chat). For external assistants use e.g. mcp_legal or external_llm when your deployment documents it.",
        "tags": [
          "AI Chat"
        ],
        "parameters": [
          {
            "name": "surface",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "crm_chat"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversations (envelope { data })",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createChatConversation",
        "summary": "Create a new AI chat conversation",
        "tags": [
          "AI Chat"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "model": {
                    "type": "string"
                  },
                  "chatSurface": {
                    "type": "string",
                    "description": "e.g. crm_chat, mcp_legal — must match your product docs"
                  },
                  "intelligenceMode": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created conversation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/chat/conversations/{conversationId}": {
      "parameters": [
        {
          "name": "conversationId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getChatConversation",
        "summary": "Get conversation with messages",
        "tags": [
          "AI Chat"
        ],
        "responses": {
          "200": {
            "description": "Conversation + messages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteChatConversation",
        "summary": "Delete a conversation",
        "tags": [
          "AI Chat"
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          }
        }
      }
    }
  }
}