{
 "openapi": "3.0.3",
 "info": {
  "title": "Truing API",
  "version": "1.0.0",
  "description": "Truing \u2014 UK entity resolution and registry signals. Domain -> company, company -> domain, with evidence."
 },
 "paths": {
  "/v1/enrich": {
   "post": {
    "summary": "Resolve and enrich a company domain",
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "domain"
        ],
        "properties": {
         "domain": {
          "type": "string"
         },
         "company_name": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cached enrichment payload"
     },
     "202": {
      "description": "Enrichment job queued"
     },
     "400": {
      "description": "Invalid request"
     },
     "401": {
      "description": "Unauthorized"
     },
     "402": {
      "description": "No credits"
     }
    }
   }
  },
  "/v1/enrich/status/{job_id}": {
   "get": {
    "summary": "Get enrichment job status",
    "parameters": [
     {
      "name": "job_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Job status"
     },
     "404": {
      "description": "Job not found"
     }
    }
   }
  },
  "/v1/resolve/domain": {
   "post": {
    "summary": "Agent-friendly domain resolution",
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "domain"
        ],
        "properties": {
         "domain": {
          "type": "string"
         },
         "company_name": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Resolution payload"
     },
     "202": {
      "description": "Resolution job queued"
     }
    }
   }
  },
  "/v1/resolve/company": {
   "post": {
    "summary": "Resolve a Companies House company profile",
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "company_number": {
          "type": "string"
         },
         "company_name": {
          "type": "string"
         },
         "refresh": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Company profile, current signals, and reverse-domain status"
     },
     "404": {
      "description": "Company not found"
     }
    }
   }
  },
  "/v1/domain-edges": {
   "post": {
    "summary": "Seed a known domain-CRN graph edge",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "company_number",
         "domain"
        ],
        "properties": {
         "company_number": {
          "type": "string"
         },
         "domain": {
          "type": "string"
         },
         "status": {
          "type": "string",
          "enum": [
           "verified",
           "probable",
           "review"
          ]
         },
         "confidence": {
          "type": "number"
         },
         "note": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Edge saved"
     },
     "400": {
      "description": "Invalid request"
     },
     "404": {
      "description": "Company not found"
     }
    }
   }
  },
  "/v1/watchlist": {
   "get": {
    "summary": "List watched companies",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Watchlist"
     }
    }
   },
   "post": {
    "summary": "Watch a company",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "company_number"
        ],
        "properties": {
         "company_number": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Company watched"
     },
     "200": {
      "description": "Already watched"
     },
     "402": {
      "description": "Watchlist limit reached"
     },
     "404": {
      "description": "Company not found"
     }
    }
   }
  },
  "/v1/watchlist/{company_number}": {
   "delete": {
    "summary": "Unwatch a company",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "company_number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Company unwatched"
     }
    }
   }
  },
  "/v1/signals": {
   "get": {
    "summary": "List watched-company signals",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "signal_type",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 1
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Scoped signal feed"
     }
    }
   }
  },
  "/v1/companies/{company_number}/signals": {
   "get": {
    "summary": "List recent signals for a company",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "company_number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 20
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Company signal history"
     },
     "404": {
      "description": "Company not found"
     }
    }
   }
  },
  "/v1/clay/webhooks": {
   "get": {
    "summary": "List webhook destinations",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Webhook list"
     }
    }
   },
   "post": {
    "summary": "Register webhook destination",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "webhook_url",
         "signal_type"
        ],
        "properties": {
         "webhook_url": {
          "type": "string",
          "format": "uri"
         },
         "signal_type": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Webhook registered"
     }
    }
   }
  },
  "/v1/clay/webhooks/{id}": {
   "delete": {
    "summary": "Delete webhook destination",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Webhook deleted"
     }
    }
   }
  },
  "/v1/auth/me": {
   "get": {
    "summary": "Account status: credits, subscription, watchlist usage, API key metadata",
    "security": [
     {
      "BearerAuth": []
     },
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Account profile with credit balance and subscription"
     },
     "401": {
      "description": "Unauthorized"
     }
    }
   }
  },
  "/v1/companies/search": {
   "get": {
    "summary": "Search the UK register by name, postcode, status, accounts type, incorporation dates",
    "security": [
     {
      "BearerAuth": []
     },
     {
      "ApiKeyAuth": []
     }
    ],
    "parameters": [
     {
      "name": "name",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "postcode",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "company_status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "accounts_type",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "incorporated_from",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "incorporated_to",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Paginated company candidates"
     },
     "401": {
      "description": "Unauthorized"
     }
    }
   }
  },
  "/v1/auth/change-password": {
   "post": {
    "summary": "Change password (requires current password)",
    "security": [
     {
      "BearerAuth": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "current_password": {
          "type": "string"
         },
         "new_password": {
          "type": "string",
          "minLength": 8
         }
        },
        "required": [
         "current_password",
         "new_password"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Password updated"
     },
     "401": {
      "description": "Current password incorrect"
     }
    }
   }
  },
  "/healthz": {
   "get": {
    "summary": "Liveness probe (includes DB reachability)",
    "responses": {
     "200": {
      "description": "Healthy"
     },
     "503": {
      "description": "Degraded"
     }
    }
   }
  },
  "/mcp": {
   "post": {
    "summary": "Hosted MCP endpoint (JSON-RPC) for AI agents \u2014 authenticate with x-api-key",
    "security": [
     {
      "ApiKeyAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "JSON-RPC response"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "BearerAuth": {
    "type": "http",
    "scheme": "bearer"
   },
   "ApiKeyAuth": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  }
 },
 "servers": [
  {
   "url": "https://api.truingdata.com"
  },
  {
   "url": "https://truingdata.com"
  }
 ]
}