{
"openapi": "3.0.3",
"info": {
"title": "Prequel Import API",
"version": "1.0.0",
"description": "API specification for importing external data into the Prequel system."
},
"paths": {
"/v1/prequel/import": {
"post": {
"summary": "Import Data",
"description": "Ingests data payload based on a specific type. The processing logic determines whether to insert or update the record based on internal identifiers.",
"operationId": "importData",
"parameters": [
{
"in": "header",
"name": "X-Prequel-Webhook-Signature",
"schema": { "type": "string" },
"required": true,
"description": "Cryptographic signature to verify the authenticity of the payload."
},
{
"in": "header",
"name": "X-Prequel-Webhook-Timestamp",
"schema": { "type": "string", "format": "date-time" },
"required": true,
"description": "Timestamp of when the webhook was fired to prevent replay attacks."
},
{
"in": "header",
"name": "X-Prequel-Webhook-Digest",
"schema": { "type": "string" },
"required": true,
"description": "Hash digest of the request body."
},
{
"in": "header",
"name": "X-Prequel-Import-Provider",
"schema": { "type": "string" },
"required": true,
"description": "Identifier for the source provider sending the data."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["type", "data"],
"properties": {
"type": {
"type": "string",
"description": "Indicates the entity type of the import. This corresponds to the Dataset name configured in Prequel Import.",
"example": "dataset_name"
},
"data": {
"type": "object",
"description": "The actual data payload. This is a free-form JSON object containing the attributes to be imported.",
"additionalProperties": true,
"example": {
"field_1": "value",
"field_2": 123,
"field_3": ["tag_1", "tag_2"]
}
}
}
}
}
}
},
"responses": {
"200": { "description": "Success - The data was successfully processed and an existing record was updated." },
"201": { "description": "Created - The data was successfully processed and a new record was inserted." },
"400": { "description": "Bad Request - Malformed JSON or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"403": { "description": "Forbidden - Invalid signature, timestamp, or provider credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"404": { "description": "Not Found - The specified type or provider configuration could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"413": { "description": "Payload Too Large - The data object exceeds the maximum allowed size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"422": { "description": "Unprocessable Entity - Validation failed for specific fields within the data object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"429": { "description": "Too Many Requests - Rate limit exceeded for this provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"431": { "description": "Request Header Fields Too Large - The header fields exceed the server limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"500": { "description": "Internal Server Error - An unexpected error occurred during processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"502": { "description": "Bad Gateway - Error communicating with upstream storage services.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"504": { "description": "Gateway Timeout - The import process timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"505": { "description": "HTTP Version Not Supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
},
"delete": {
"summary": "Delete Data",
"description": "Deletes records based on the provided data payload and type. Accepts identifiers in the data object to locate and remove the resource.",
"operationId": "deleteData",
"parameters": [
{
"in": "header",
"name": "X-Prequel-Webhook-Signature",
"schema": { "type": "string" },
"required": true,
"description": "Cryptographic signature to verify the authenticity of the payload."
},
{
"in": "header",
"name": "X-Prequel-Webhook-Timestamp",
"schema": { "type": "string", "format": "date-time" },
"required": true,
"description": "Timestamp of when the webhook was fired."
},
{
"in": "header",
"name": "X-Prequel-Webhook-Digest",
"schema": { "type": "string" },
"required": true,
"description": "Hash digest of the request body."
},
{
"in": "header",
"name": "X-Prequel-Import-Provider",
"schema": { "type": "string" },
"required": true,
"description": "Identifier for the source provider requesting the delete."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["type", "data"],
"properties": {
"type": {
"type": "string",
"description": "Indicates the entity type to delete.",
"example": "dataset_name"
},
"data": {
"type": "object",
"description": "JSON object containing identifiers for the record(s) to be deleted.",
"additionalProperties": true,
"example": { "id": "record_id" }
}
}
}
}
}
},
"responses": {
"200": { "description": "Success - The record was found and successfully deleted." },
"400": { "description": "Bad Request - Malformed JSON or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"403": { "description": "Forbidden - Invalid signature or insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"404": { "description": "Not Found - The specified record to delete could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
"500": { "description": "Internal Server Error - An unexpected error occurred during deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
}
}
}
},
"components": {
"schemas": {
"ErrorResponse": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": { "type": "string", "description": "A machine-readable error code.", "example": "INVALID_SIGNATURE" },
"message": { "type": "string", "description": "A human-readable description of the error.", "example": "The provided webhook signature does not match the expected value." },
"details": { "type": "object", "description": "Optional additional details about validation failures." }
}
}
}
}
}
}
}
