{
 "openapi": "3.1.0",
 "info": {
  "title": "Unicorn Intelligence API",
  "version": "1.0.0",
  "description": "Sanctions and counterparty screening, company dossiers, competitor and sector intelligence, regulatory monitoring and public tenders. Information tool: decisions and legal obligations remain with the customer. Every item carries its source and date. Plans (ids returned by GET /v1/usage): screening_100, screening_1k, screening_10k, dossier_10, sector, regulation_3, regulation_10, tenders, sanctions, compliance, growth, complete. The API is not included in the Start plan ($0): calls return 403 plan_upgrade_required. Monthly plans by card with automatic renewal; annual plans (10 months for 12) by card or bank transfer. Prices: https://intel.unicornprivate.com/pricing/",
  "termsOfService": "https://intel.unicornprivate.com/terms/",
  "contact": {
   "url": "https://intel.unicornprivate.com/docs"
  }
 },
 "servers": [
  {
   "url": "https://intel.unicornprivate.com"
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "API key ui_live_... created by an admin in the dashboard."
   }
  },
  "responses": {
   "Error": {
    "description": "Error",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "status": {
        "type": "integer"
       },
       "docs": {
        "type": "string"
       }
      }
     }
    }
   },
   "Entity": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "ref": {
      "type": "string",
      "description": "Your reference (letters, digits . _ : / -, max 80). Generated from the name if missing."
     },
     "name": {
      "type": "string"
     },
     "type": {
      "type": "string",
      "enum": [
       "company",
       "person"
      ]
     },
     "country": {
      "type": "string"
     },
     "aliases": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "dob": {
      "type": "string",
      "description": "YYYY, YYYY-MM or YYYY-MM-DD"
     },
     "lei": {
      "type": "string"
     },
     "website": {
      "type": "string"
     }
    }
   },
   "Match": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "ref": {
      "type": "string"
     },
     "entityName": {
      "type": "string"
     },
     "list": {
      "type": "string"
     },
     "listEntryId": {
      "type": "string"
     },
     "listName": {
      "type": "string"
     },
     "score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
     },
     "reasons": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "sourceUrl": {
      "type": "string"
     },
     "listedAt": {
      "type": [
       "string",
       "null"
      ]
     },
     "detectedAt": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "open",
       "cleared",
       "confirmed"
      ]
     }
    }
   },
   "AuditEntry": {
    "type": "object",
    "properties": {
     "at": {
      "type": "string"
     },
     "action": {
      "type": "string"
     },
     "matchId": {
      "type": "string"
     },
     "ref": {
      "type": "string"
     },
     "fromStatus": {
      "type": "string"
     },
     "toStatus": {
      "type": "string"
     },
     "note": {
      "type": "string"
     }
    }
   },
   "Dossier": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "queued",
       "running",
       "ready",
       "failed"
      ]
     },
     "summary": {
      "type": "string"
     },
     "sections": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "pdfUrl": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "Item": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "module": {
      "type": "string",
      "enum": [
       "sector",
       "regulation",
       "tenders"
      ]
     },
     "title": {
      "type": "string"
     },
     "summary": {
      "type": "string"
     },
     "language": {
      "type": "string"
     },
     "country": {
      "type": "string"
     },
     "publishedAt": {
      "type": "string"
     },
     "deadline": {
      "type": "string"
     },
     "value": {
      "type": "number"
     },
     "currency": {
      "type": "string"
     },
     "sourceName": {
      "type": "string"
     },
     "sourceUrl": {
      "type": "string"
     },
     "relevance": {
      "type": "number"
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "Profile": {
    "type": "object",
    "properties": {
     "languages": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "countries": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "sectors": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "keywords": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "competitors": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "name": {
         "type": "string"
        },
        "website": {
         "type": "string"
        }
       }
      }
     },
     "cpv": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "minValue": {
      "type": [
       "number",
       "null"
      ]
     },
     "tenderProfiles": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   },
   "Webhook": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "url": {
      "type": "string"
     },
     "types": {
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "match",
        "dossier_ready",
        "news",
        "sector",
        "regulation",
        "tenders"
       ]
      }
     },
     "active": {
      "type": "boolean"
     },
     "secret": {
      "type": "string",
      "description": "Only in the creation response."
     }
    }
   }
  }
 },
 "paths": {
  "/v1/status": {
   "get": {
    "summary": "Service and sources status",
    "security": [],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/v1/usage": {
   "get": {
    "summary": "Plan, modules, limits and usage of the month",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/entities": {
   "get": {
    "summary": "List monitored names",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Search",
      "required": false
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer"
      },
      "description": "",
      "required": false
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "maximum": 500
      },
      "description": "",
      "required": false
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Entity"
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "post": {
    "summary": "Add or update names (upsert by ref, up to 5,000 per call)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "entities": {
          "type": "array",
          "items": {
           "$ref": "#/components/schemas/Entity"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "object",
           "properties": {
            "added": {
             "type": "integer"
            },
            "updated": {
             "type": "integer"
            },
            "total": {
             "type": "integer"
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "delete": {
    "summary": "Remove names",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "refs": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/screen": {
   "post": {
    "summary": "Instant check of up to 100 names without saving them",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "entities": {
          "type": "array",
          "items": {
           "$ref": "#/components/schemas/Entity"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/matches": {
   "get": {
    "summary": "Matches",
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "open",
        "cleared",
        "confirmed"
       ]
      },
      "description": "",
      "required": false
     },
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO 8601",
      "required": false
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "maximum": 1000
      },
      "description": "",
      "required": false
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Match"
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/matches/{id}/review": {
   "post": {
    "summary": "Confirm or clear a match (recorded in the audit log)",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Match id"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "status"
        ],
        "properties": {
         "status": {
          "type": "string",
          "enum": [
           "confirmed",
           "cleared",
           "open"
          ]
         },
         "note": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/audit": {
   "get": {
    "summary": "Audit log of review decisions (JSON, or CSV with format=csv)",
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO 8601",
      "required": false
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer"
      },
      "description": "",
      "required": false
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "csv"
       ]
      },
      "description": "",
      "required": false
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/AuditEntry"
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/dossiers": {
   "get": {
    "summary": "List dossiers",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Dossier"
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "post": {
    "summary": "Request a dossier (uses one dossier of the month or one purchased dossier)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "website": {
          "type": "string"
         },
         "country": {
          "type": "string"
         },
         "lei": {
          "type": "string"
         },
         "language": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/Dossier"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "402": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/dossiers/{id}": {
   "get": {
    "summary": "Dossier (JSON)",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Dossier id"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/Dossier"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/dossiers/{id}.pdf": {
   "get": {
    "summary": "Dossier (PDF)",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Dossier id"
     }
    ],
    "responses": {
     "200": {
      "description": "PDF",
      "content": {
       "application/pdf": {}
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/profile": {
   "get": {
    "summary": "Monitoring profile and limits",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "put": {
    "summary": "Replace the monitoring profile",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Profile"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/feed": {
   "get": {
    "summary": "Feed of sector, regulation or tenders items",
    "parameters": [
     {
      "name": "module",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "sector",
        "regulation",
        "tenders"
       ]
      },
      "description": "",
      "required": true
     },
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO 8601",
      "required": false
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "maximum": 200
      },
      "description": "",
      "required": false
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer"
      },
      "description": "",
      "required": false
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Item"
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/briefings": {
   "get": {
    "summary": "Weekly briefing",
    "parameters": [
     {
      "name": "module",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "sector",
        "regulation",
        "tenders"
       ]
      },
      "description": "",
      "required": true
     },
     {
      "name": "week",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO week, e.g. 2026-W44 (default: last week)",
      "required": false
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/webhooks": {
   "get": {
    "summary": "List webhook endpoints",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Webhook"
           }
          },
          "meta": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   },
   "post": {
    "summary": "Create a webhook endpoint (secret returned once)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "url"
        ],
        "properties": {
         "url": {
          "type": "string"
         },
         "types": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/Webhook"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/webhooks/{id}": {
   "delete": {
    "summary": "Delete a webhook endpoint",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Endpoint id"
     }
    ],
    "responses": {
     "204": {
      "description": "Deleted"
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/v1/webhooks/{id}/test": {
   "post": {
    "summary": "Send a test event now",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Endpoint id"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  }
 }
}