{
  "openapi": "3.0.3",
  "info": {
    "title": "FormPilot Integration API",
    "version": "1.0.0",
    "description": "Development API; no direct GIB/SGK/marketplace connector. See integration-guide.txt."
  },
  "servers": [
    {
      "url": "/api/integrations/v1"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "OwnerSession": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/imports": {
      "post": {
        "summary": "Structured fields and tables; imports:write",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued job: id and state"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or expired key"
          },
          "403": {
            "description": "Scope or subscription required"
          },
          "409": {
            "description": "Idempotency conflict"
          },
          "429": {
            "description": "Queue or rate limit"
          }
        }
      }
    },
    "/documents": {
      "post": {
        "summary": "Multipart file upload; documents:write",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued job: id and state"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or expired key"
          },
          "403": {
            "description": "Scope or subscription required"
          },
          "409": {
            "description": "Idempotency conflict"
          },
          "429": {
            "description": "Queue or rate limit"
          }
        }
      }
    },
    "/matches": {
      "post": {
        "summary": "Batched matching; matches:write",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{8,100}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued job: id and state"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid or expired key"
          },
          "403": {
            "description": "Scope or subscription required"
          },
          "409": {
            "description": "Idempotency conflict"
          },
          "429": {
            "description": "Queue or rate limit"
          }
        }
      }
    },
    "/jobs/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Status/result; jobs:read",
        "responses": {
          "200": {
            "description": "id,state,progress,total,error,result,expires"
          },
          "404": {
            "description": "Missing, expired or different owner"
          }
        }
      },
      "delete": {
        "summary": "Delete job; jobs:delete",
        "responses": {
          "204": {
            "description": "Deleted; running provider requests may finish"
          }
        }
      }
    },
    "/keys": {
      "post": {
        "security": [
          {
            "OwnerSession": []
          }
        ],
        "summary": "Create a scoped key; requires owner extension session",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "imports:write",
                        "documents:write",
                        "matches:write",
                        "jobs:read",
                        "jobs:delete"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "id,key,scopes,expiresInDays; key shown once"
          }
        }
      }
    },
    "/keys/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "security": [
          {
            "OwnerSession": []
          }
        ],
        "summary": "Revoke own API key",
        "responses": {
          "204": {
            "description": "Revoked"
          }
        }
      }
    }
  }
}