{
  "openapi": "3.0.0",
  "info": {
    "description": "OpenAPI specification for Messari Deep Research API",
    "title": "Messari API - Deep Research V1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "description": "Messari API",
      "url": "https://api.messari.io"
    }
  ],
  "security": [],
  "paths": {
    "/ai/v1/deep-research": {
      "get": {
        "description": "Returns a paginated list of deep research jobs for the authenticated user. Optionally filter by status using the 'status' query parameter.",
        "operationId": "listDeepResearch",
        "parameters": [
          {
            "description": "Maximum number of jobs to return (default 20, max 100)",
            "in": "query",
            "name": "limit",
            "required": true,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "Number of jobs to skip for pagination",
            "in": "query",
            "name": "offset",
            "required": true,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "Filter jobs by status: queued, in_progress, completed, failed, cancelled",
            "in": "query",
            "name": "status",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "List of deep research jobs",
                      "items": {
                        "$ref": "#/components/schemas/DeepResearchResponse"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Default response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Bad Request"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unauthorized"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "List deep research jobs"
      },
      "post": {
        "description": "Starts a new deep research report generation. The job runs asynchronously and typically takes 5-10 minutes to complete. Use the returned job ID to poll for status and results via GET /v1/deep-research/:id. Consumes 500 credits. Enterprise teams receive 10 free report generations per month (shared with the Messari platform) which are consumed before credits. Optionally provide a job_id to send a follow-up message for iterative refinement of an existing report.",
        "operationId": "postDeepResearch",
        "requestBody": {
          "content": {
            "*/*": {
              "schema": {
                "$ref": "#/components/schemas/DeepResearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "created_at": {
                      "description": "Unix timestamp when the job was created",
                      "format": "int64",
                      "type": "integer"
                    },
                    "job_id": {
                      "description": "Unique identifier for the deep research job",
                      "format": "byte",
                      "type": "string"
                    },
                    "model": {
                      "description": "Model used for the deep research",
                      "type": "string"
                    },
                    "object": {
                      "description": "Type of object returned, always 'deep_research'",
                      "type": "string"
                    },
                    "query": {
                      "description": "The research query that was submitted for this job",
                      "type": "string"
                    },
                    "status": {
                      "description": "Current status of the deep research job: queued, in_progress, completed, failed, cancelled",
                      "type": "string"
                    }
                  },
                  "required": [
                    "created_at",
                    "job_id",
                    "model",
                    "object",
                    "query",
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Default response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Bad Request"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unauthorized"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Create a deep research job"
      }
    },
    "/ai/v1/deep-research/{id}": {
      "get": {
        "description": "Returns the current status of a deep research job. When status is 'completed', the response includes the generated report and sources. Poll this endpoint to check progress.",
        "operationId": "getDeepResearch",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "created_at": {
                      "description": "Unix timestamp when the job was created",
                      "format": "int64",
                      "type": "integer"
                    },
                    "error": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/DeepResearchError"
                        },
                        {
                          "description": "Error details, populated when status is 'failed'"
                        }
                      ]
                    },
                    "job_id": {
                      "description": "Unique identifier for the deep research job",
                      "format": "byte",
                      "type": "string"
                    },
                    "model": {
                      "description": "Model used for the deep research",
                      "type": "string"
                    },
                    "object": {
                      "description": "Type of object returned, always 'deep_research'",
                      "type": "string"
                    },
                    "output": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/DeepResearchOutput"
                        },
                        {
                          "description": "The research output, populated when status is 'completed'"
                        }
                      ]
                    },
                    "query": {
                      "description": "The research query that was submitted for this job",
                      "type": "string"
                    },
                    "status": {
                      "description": "Current status of the deep research job: queued, in_progress, completed, failed, cancelled",
                      "type": "string"
                    }
                  },
                  "required": [
                    "created_at",
                    "job_id",
                    "model",
                    "object",
                    "query",
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Default response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Bad Request"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unauthorized"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get deep research job status and result"
      }
    },
    "/ai/v1/deep-research/{id}/cancel": {
      "post": {
        "description": "Requests cancellation of a running deep research job. Only jobs with status 'queued' or 'in_progress' can be cancelled. The job's status will transition to 'cancelled'.",
        "operationId": "cancelDeepResearch",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "job_id": {
                      "description": "Unique identifier for the cancelled deep research job",
                      "format": "byte",
                      "type": "string"
                    },
                    "object": {
                      "description": "Type of object returned, always 'deep_research'",
                      "type": "string"
                    },
                    "status": {
                      "description": "Status of the job after cancellation",
                      "type": "string"
                    }
                  },
                  "required": [
                    "job_id",
                    "object",
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Default response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Bad Request"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Unauthorized"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {},
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Cancel a deep research job"
      }
    }
  },
  "components": {
    "schemas": {
      "DeepResearchError": {
        "properties": {
          "code": {
            "description": "A machine-readable error code: insufficient_credits, timeout, internal_error, cancelled",
            "type": "string"
          },
          "message": {
            "description": "A human-readable error message describing the failure",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "DeepResearchOutput": {
        "properties": {
          "report": {
            "description": "The generated deep research report in markdown format",
            "type": "string"
          },
          "sources": {
            "description": "Sources cited in the report",
            "items": {
              "$ref": "#/components/schemas/DeepResearchSource"
            },
            "type": "array"
          }
        },
        "required": [
          "report"
        ],
        "type": "object"
      },
      "DeepResearchRequest": {
        "properties": {
          "instructions": {
            "description": "Optional system instructions to guide the research process and report generation style",
            "type": "string"
          },
          "job_id": {
            "description": "Optional UUID of an existing deep research conversation to continue with a follow-up message",
            "format": "byte",
            "type": "string"
          },
          "query": {
            "description": "The research query or topic for the deep research report",
            "type": "string"
          }
        },
        "required": [
          "query"
        ],
        "type": "object"
      },
      "DeepResearchResponse": {
        "properties": {
          "created_at": {
            "description": "Unix timestamp when the job was created",
            "format": "int64",
            "type": "integer"
          },
          "job_id": {
            "description": "Unique identifier for the deep research job",
            "format": "byte",
            "type": "string"
          },
          "model": {
            "description": "Model used for the deep research",
            "type": "string"
          },
          "object": {
            "description": "Type of object returned, always 'deep_research'",
            "type": "string"
          },
          "query": {
            "description": "The research query that was submitted for this job",
            "type": "string"
          },
          "status": {
            "description": "Current status of the deep research job: queued, in_progress, completed, failed, cancelled",
            "type": "string"
          }
        },
        "required": [
          "created_at",
          "job_id",
          "model",
          "object",
          "query",
          "status"
        ],
        "type": "object"
      },
      "DeepResearchSource": {
        "properties": {
          "citationId": {
            "format": "int64",
            "type": "integer"
          },
          "domain": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKey": {
        "in": "header",
        "name": "X-Messari-API-Key",
        "type": "apiKey"
      }
    }
  }
}