{
 "swagger": "2.0",
 "info": {
  "title": "Agent002 Forms",
  "version": "1.0",
  "description": "Read your forms and their responses, and get each new response the moment it arrives. Make a key on the Connections page of the app (owners, paid Business plans). Guide: https://agent002.eu/help/api",
  "contact": {
   "name": "Agent002",
   "url": "https://agent002.eu/help/api",
   "email": "hello@agent002.eu"
  }
 },
 "host": "forms.agent002.eu",
 "basePath": "/api/v1",
 "schemes": [
  "https"
 ],
 "consumes": [
  "application/json"
 ],
 "produces": [
  "application/json"
 ],
 "securityDefinitions": {
  "apiKey": {
   "type": "apiKey",
   "in": "header",
   "name": "X-Api-Key",
   "description": "Your API key (a002_…). \"Authorization: Bearer a002_…\" works too."
  }
 },
 "security": [
  {
   "apiKey": []
  }
 ],
 "paths": {
  "/me": {
   "get": {
    "operationId": "Me",
    "summary": "The account this key belongs to",
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "type": "object",
       "properties": {
        "organization": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "name": {
           "type": "string"
          }
         }
        },
        "plan": {
         "type": "string"
        },
        "key": {
         "type": "object",
         "properties": {
          "name": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/forms": {
   "get": {
    "operationId": "ListForms",
    "summary": "Your forms",
    "description": "Newest first.",
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "type": "array",
       "items": {
        "$ref": "#/definitions/Form"
       }
      }
     }
    }
   }
  },
  "/forms/{formId}": {
   "get": {
    "operationId": "GetForm",
    "summary": "A form and its questions",
    "parameters": [
     {
      "$ref": "#/parameters/formId"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "$ref": "#/definitions/FormDetail"
      }
     },
     "404": {
      "description": "No such form"
     }
    }
   }
  },
  "/forms/{formId}/responses": {
   "get": {
    "operationId": "ListResponses",
    "summary": "A form's responses",
    "description": "Newest first, in the same shape webhooks get.",
    "parameters": [
     {
      "$ref": "#/parameters/formId"
     },
     {
      "name": "limit",
      "in": "query",
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25,
      "description": "How many (1–100)."
     },
     {
      "name": "before",
      "in": "query",
      "type": "string",
      "format": "uuid",
      "description": "A response id: the ones before it, to page back."
     },
     {
      "name": "sample",
      "in": "query",
      "type": "boolean",
      "description": "With no responses yet, return one made-up response built from the questions.",
      "x-ms-visibility": "internal"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "type": "array",
       "items": {
        "$ref": "#/definitions/Response"
       }
      }
     }
    }
   }
  },
  "/forms/{formId}/responses/{responseId}": {
   "get": {
    "operationId": "GetResponse",
    "summary": "One response",
    "parameters": [
     {
      "$ref": "#/parameters/formId"
     },
     {
      "name": "responseId",
      "in": "path",
      "required": true,
      "type": "string",
      "format": "uuid"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "$ref": "#/definitions/Response"
      }
     },
     "404": {
      "description": "No such response"
     }
    }
   }
  },
  "/hooks": {
   "get": {
    "operationId": "ListHooks",
    "summary": "Webhooks added through the API",
    "responses": {
     "200": {
      "description": "OK",
      "schema": {
       "type": "array",
       "items": {
        "$ref": "#/definitions/Hook"
       }
      }
     }
    }
   },
   "post": {
    "operationId": "WhenResponseArrives",
    "summary": "When a new response arrives",
    "description": "Subscribes a URL to a form's new responses. Each one is POSTed there as JSON, signed with X-Agent002-Signature, with retries. The answer has the webhook's id and, this once, its signing secret (secret): keep it to check the signature, sha256=HMAC-SHA256(secret, X-Agent002-Timestamp + \".\" + body). Remove the webhook with DELETE /hooks/{id}.",
    "x-ms-trigger": "single",
    "parameters": [
     {
      "name": "body",
      "in": "body",
      "required": true,
      "schema": {
       "type": "object",
       "required": [
        "form",
        "url"
       ],
       "properties": {
        "form": {
         "type": "string",
         "format": "uuid",
         "description": "The form's id",
         "x-ms-dynamic-values": {
          "operationId": "ListForms",
          "value-path": "id",
          "value-title": "name"
         }
        },
        "url": {
         "type": "string",
         "description": "Where to send each response (https)",
         "x-ms-notification-url": true,
         "x-ms-visibility": "internal"
        },
        "name": {
         "type": "string",
         "description": "Shown under the form's Destinations (the key's name if empty)"
        }
       }
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Subscribed",
      "schema": {
       "$ref": "#/definitions/Response"
      },
      "headers": {
       "Location": {
        "type": "string",
        "description": "The webhook's address, to remove it"
       }
      }
     }
    }
   }
  },
  "/hooks/{hookId}": {
   "delete": {
    "operationId": "RemoveHook",
    "summary": "Stop sending responses to a webhook",
    "x-ms-visibility": "internal",
    "parameters": [
     {
      "name": "hookId",
      "in": "path",
      "required": true,
      "type": "string",
      "format": "uuid"
     }
    ],
    "responses": {
     "204": {
      "description": "Removed"
     }
    }
   }
  },
  "/openapi.json": {
   "get": {
    "operationId": "OpenApi",
    "summary": "This description",
    "security": [],
    "x-ms-visibility": "internal",
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  }
 },
 "parameters": {
  "formId": {
   "name": "formId",
   "in": "path",
   "required": true,
   "type": "string",
   "format": "uuid",
   "description": "The form's id",
   "x-ms-dynamic-values": {
    "operationId": "ListForms",
    "value-path": "id",
    "value-title": "name"
   }
  }
 },
 "definitions": {
  "Form": {
   "type": "object",
   "properties": {
    "id": {
     "type": "string",
     "format": "uuid"
    },
    "name": {
     "type": "string"
    },
    "status": {
     "type": "string",
     "enum": [
      "draft",
      "published",
      "closed"
     ]
    },
    "link": {
     "type": "string"
    },
    "responses": {
     "type": "integer"
    },
    "createdAt": {
     "type": "string",
     "format": "date-time"
    }
   }
  },
  "FormDetail": {
   "type": "object",
   "properties": {
    "id": {
     "type": "string",
     "format": "uuid"
    },
    "name": {
     "type": "string"
    },
    "status": {
     "type": "string"
    },
    "link": {
     "type": "string"
    },
    "version": {
     "type": "integer"
    },
    "questions": {
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "key": {
        "type": "string"
       },
       "label": {
        "type": "string"
       },
       "type": {
        "type": "string"
       },
       "required": {
        "type": "boolean"
       },
       "options": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "value": {
           "type": "string"
          },
          "label": {
           "type": "string"
          }
         }
        }
       },
       "other": {
        "type": "boolean",
        "description": "A choice with \"Other\": the answer can be words typed instead of an option's value."
       },
       "parts": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "key": {
           "type": "string"
          },
          "label": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "Response": {
   "type": "object",
   "properties": {
    "event": {
     "type": "string",
     "description": "submission.created (or submission.sample / submission.test)"
    },
    "form": {
     "type": "object",
     "properties": {
      "id": {
       "type": "string",
       "format": "uuid"
      },
      "name": {
       "type": "string"
      },
      "slug": {
       "type": "string"
      }
     }
    },
    "version": {
     "type": "integer"
    },
    "submission": {
     "type": "object",
     "properties": {
      "id": {
       "type": "string",
       "format": "uuid"
      },
      "createdAt": {
       "type": "string",
       "format": "date-time"
      },
      "answers": {
       "type": "object",
       "additionalProperties": true,
       "description": "Answers keyed by question key."
      }
     }
    },
    "questions": {
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "key": {
        "type": "string"
       },
       "label": {
        "type": "string"
       },
       "type": {
        "type": "string"
       }
      }
     }
    },
    "fields": {
     "type": "array",
     "description": "Every question in form order, with its answer as text.",
     "items": {
      "type": "object",
      "properties": {
       "key": {
        "type": "string"
       },
       "label": {
        "type": "string"
       },
       "type": {
        "type": "string"
       },
       "value": {},
       "text": {
        "type": "string"
       }
      }
     }
    }
   }
  },
  "Hook": {
   "type": "object",
   "properties": {
    "id": {
     "type": "string",
     "format": "uuid"
    },
    "form": {
     "type": "string",
     "format": "uuid"
    },
    "formName": {
     "type": "string"
    },
    "url": {
     "type": "string"
    },
    "name": {
     "type": "string"
    },
    "createdAt": {
     "type": "string",
     "format": "date-time"
    }
   }
  }
 }
}