diff --git a/admin-openapi.json b/admin-openapi.json new file mode 100644 index 000000000..8b2d7b4f7 --- /dev/null +++ b/admin-openapi.json @@ -0,0 +1,357 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "Mintlify Admin API", + "description": "An API for administrative operations including documentation updates and agent management.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.mintlify.com/v1" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/admin/update/{domain}": { + "post": { + "summary": "Trigger update", + "description": "Triggers an update of your documentation site.", + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." + } + ], + "responses": { + "200": { + "description": "Update triggered successfully" + } + } + } + }, + "/admin/update/{domain}/status": { + "get": { + "summary": "Get update status", + "description": "Retrieves the status of documentation updates and other details about your docs.", + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." + } + ], + "responses": { + "200": { + "description": "Update status retrieved successfully" + } + } + } + }, + "/agent/job/{projectId}": { + "post": { + "summary": "Create agent job", + "description": "Creates a new agent job that can generate and edit documentation based on provided messages and branch information.", + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of your project. Can be retrieved from your dashboard." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "branch", + "messages" + ], + "properties": { + "branch": { + "type": "string", + "description": "The name of the Git branch that the agent should work on, will be automatically created if it doesn't exist" + }, + "messages": { + "type": "array", + "description": "A list of previous messages to provide to the agent.", + "items": { + "type": "object", + "required": [ + "role", + "content" + ], + "properties": { + "role": { + "type": "string", + "enum": ["system", "user"], + "description": "The role of the message sender." + }, + "content": { + "type": "string", + "description": "The content of the message." + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Agent job created successfully (streaming response). X-Session-Id Header is sent back in the response", + "headers": { + "X-Message-Id": { + "schema": { + "type": "string" + }, + "description": "Message identifier for the created job" + } + }, + "content": { + "text/plain": { + "schema": { + "type": "string", + "description": "Streaming response containing the agent job execution details and results." + } + } + } + } + } + } + }, + "/agent/{projectId}/job/{id}": { + "get": { + "summary": "Get agent job by ID", + "description": "Retrieves the details and status of a specific agent job by its ID.", + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of your project. Can be retrieved from your dashboard." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the agent job to retrieve." + } + ], + "responses": { + "200": { + "description": "Agent job details retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "The subdomain this session belongs to." + }, + "subdomain": { + "type": "string", + "description": "The subdomain this session belongs to." + }, + "branch": { + "type": "string", + "description": "Git branch name where changes were made.", + "nullable": true + }, + "haulted": { + "type": "boolean", + "description": "Whether the session execution was halted." + }, + "haultReason": { + "type": "string", + "enum": ["completed", "github_missconfigured", "error"], + "description": "Reason for session halt." + }, + "pullRequestLink": { + "type": "string", + "description": "Link to the created pull request." + }, + "messageToUser": { + "type": "string", + "description": "Message for the user about the session outcome." + }, + "todos": { + "type": "array", + "description": "List of todo items from the session.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Brief description of the task." + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "cancelled"], + "description": "Current status of the task." + }, + "priority": { + "type": "string", + "enum": ["high", "medium", "low"], + "description": "Priority level of the task." + }, + "id": { + "type": "string", + "description": "Unique identifier for the todo item." + } + } + } + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the session was created." + } + } + } + } + } + } + } + } + }, + "/agent/{projectId}/jobs": { + "get": { + "summary": "Get all agent jobs", + "description": "Retrieves all agent jobs for the specified domain, including their status and details.", + "parameters": [ + { + "name": "projectId", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The ID of your project. Can be retrieved from your dashboard." + } + ], + "responses": { + "200": { + "description": "All agent jobs retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "allSessions": { + "type": "array", + "description": "Array of all agent sessions for the domain.", + "items": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "The subdomain this session belongs to." + }, + "subdomain": { + "type": "string", + "description": "The subdomain this session belongs to." + }, + "branch": { + "type": "string", + "description": "Git branch name where changes were made.", + "nullable": true + }, + "haulted": { + "type": "boolean", + "description": "Whether the session execution was halted." + }, + "haultReason": { + "type": "string", + "enum": ["completed", "github_missconfigured", "error"], + "description": "Reason for session halt." + }, + "pullRequestLink": { + "type": "string", + "description": "Link to the created pull request." + }, + "messageToUser": { + "type": "string", + "description": "Message for the user about the session outcome." + }, + "todos": { + "type": "array", + "description": "List of todo items from the session.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Brief description of the task." + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "cancelled"], + "description": "Current status of the task." + }, + "priority": { + "type": "string", + "enum": ["high", "medium", "low"], + "description": "Priority level of the task." + }, + "id": { + "type": "string", + "description": "Unique identifier for the todo item." + } + } + } + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the session was created." + } + } + } + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer", + "description": "The Authorization header expects a Bearer token. Create an [Admin API Key](https://dashboard.mintlify.com/settings/organization/api-keys) here." + } + } + } +} diff --git a/api-reference/agent/create-agent-job.mdx b/api-reference/agent/create-agent-job.mdx index b21502eb3..7bfa41529 100644 --- a/api-reference/agent/create-agent-job.mdx +++ b/api-reference/agent/create-agent-job.mdx @@ -1,5 +1,5 @@ --- -openapi: POST /agent/job/{domain} +openapi: POST /agent/job/{projectId} --- This endpoint creates an agent job based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results. @@ -10,9 +10,7 @@ If a branch doesn't exist, the agent creates one. If files are edited successful The agent API has the following limits: -- 10,000 uses per key per month -- 10,000 requests per Mintlify organization per hour -- 10,000 requests per IP per day +- 100 uses per Mintlify project per hour ## Suggested usage diff --git a/api-reference/agent/get-agent-job.mdx b/api-reference/agent/get-agent-job.mdx index e24430aae..74612aea4 100644 --- a/api-reference/agent/get-agent-job.mdx +++ b/api-reference/agent/get-agent-job.mdx @@ -1,5 +1,5 @@ --- -openapi: GET /agent/{domain}/job/{id} +openapi: GET /agent/{projectId}/job/{id} --- ## Usage diff --git a/api-reference/agent/get-all-jobs.mdx b/api-reference/agent/get-all-jobs.mdx index 51a586573..12bd4ec8c 100644 --- a/api-reference/agent/get-all-jobs.mdx +++ b/api-reference/agent/get-all-jobs.mdx @@ -1,5 +1,5 @@ --- -openapi: GET /agent/{domain}/jobs +openapi: GET /agent/{projectId}/jobs --- ## Usage diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 2a446431d..f51ec9831 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -10,6 +10,9 @@ The Mintlify REST API enables you to programmatically interact with your documen - [Trigger update](/api-reference/update/trigger): Trigger an update of your site when desired. - [Get update status](/api-reference/update/status): Get the status of an update and other details about your docs. +- [Create agent job](/api-reference/agent/create-agent-job): Create an agent job to automatically edit your documentation. +- [Get agent job](/api-reference/agent/get-agent-job): Retrieve the details and status of a specific agent job. +- [Get all agent jobs](/api-reference/agent/get-all-jobs): Retrieve all agent jobs for a domain. - [Generate assistant message](/api-reference/assistant/create-assistant-message): Embed the assistant, trained on your docs, into any application of your choosing. - [Search documentation](/api-reference/assistant/search): Search through your documentation. @@ -19,7 +22,7 @@ You can generate an API key through [the dashboard](https://dashboard.mintlify.c ### Admin API key -The admin API key is used for the [Trigger update](/api-reference/update/trigger) and [Get update status](/api-reference/update/status) endpoints. +The admin API key is used for the [Trigger update](/api-reference/update/trigger), [Get update status](/api-reference/update/status), and all agent endpoints. Admin API keys begin with the `mint_` prefix. Keep your admin API keys secret. diff --git a/discovery-openapi.json b/discovery-openapi.json index 0cbb4ddde..1dfe87c04 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -485,7 +485,7 @@ "text/plain": { "schema": { "type": "string", - "description": "A text stream in the form `||[chunks]`. The chunks are parts of your docs that most closely matched the user query. Each has the following format: \n ```\n { \n \tid: string;\n \tlink: string;\n \tchunk_html: string;\n \tmetadata: {\n \t\ttitle?: string\n \t}\n} \n``` \n The links are relative links with your docs URL intended as the host. To get an absolute link to your docs, you can use the `X-Mintlify-Base-Url` header as the host and construct a fully-qualified URL." + "description": "A text stream in the form `||[chunks]`. The chunks are parts of your docs that most closely matched the user query. Each has the following format: \\n ```\\n { \\n \\tid: string;\\n \\tlink: string;\\n \\tchunk_html: string;\\n \\tmetadata: {\\n \\t\\ttitle?: string\\n \\t}\\n} \\n``` \\n The links are relative links with your docs URL intended as the host. To get an absolute link to your docs, you can use the `X-Mintlify-Base-Url` header as the host and construct a fully-qualified URL." } } } @@ -576,290 +576,6 @@ } } } - }, - "/agent/job/{domain}": { - "post": { - "summary": "Create agent job", - "description": "Creates a new agent job that can generate and edit documentation based on provided messages and branch information.", - "parameters": [ - { - "name": "domain", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "branch", - "messages", - ], - "properties": { - "branch": { - "type": "string", - "description": "The name of the Git branch that the agent should work on, will be automatically created if it doesn't exist" - }, - "messages": { - "type": "array", - "description": "A list of previous messages to provide to the agent.", - "items": { - "type": "object", - "required": [ - "role", - "content" - ], - "properties": { - "role": { - "type": "string", - "enum": ["system", "user"], - "description": "The role of the message sender." - }, - "content": { - "type": "string", - "description": "The content of the message." - } - } - } - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Agent job created successfully (streaming response). X-Session-Id Header is sent back in the response", - "headers": { - "X-Message-Id": { - "schema": { - "type": "string" - }, - "description": "Message identifier for the created job" - } - }, - "content": { - "text/plain": { - "schema": { - "type": "string", - "description": "Streaming response containing the agent job execution details and results." - } - } - } - } - } - } - }, - "/agent/{domain}/job/{id}": { - "get": { - "summary": "Get agent job by ID", - "description": "Retrieves the details and status of a specific agent job by its ID.", - "parameters": [ - { - "name": "domain", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." - }, - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "The unique identifier of the agent job to retrieve." - } - ], - "responses": { - "200": { - "description": "Agent job details retrieved successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "sessionId": { - "type": "string", - "description": "The subdomain this session belongs to." - }, - "subdomain": { - "type": "string", - "description": "The subdomain this session belongs to." - }, - "branch": { - "type": "string", - "description": "Git branch name where changes were made.", - "nullable": true - }, - "haulted": { - "type": "boolean", - "description": "Whether the session execution was halted." - }, - "haultReason": { - "type": "string", - "enum": ["completed", "github_missconfigured", "error"], - "description": "Reason for session halt." - }, - "pullRequestLink": { - "type": "string", - "description": "Link to the created pull request." - }, - "messageToUser": { - "type": "string", - "description": "Message for the user about the session outcome." - }, - "todos": { - "type": "array", - "description": "List of todo items from the session.", - "items": { - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "Brief description of the task." - }, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "completed", "cancelled"], - "description": "Current status of the task." - }, - "priority": { - "type": "string", - "enum": ["high", "medium", "low"], - "description": "Priority level of the task." - }, - "id": { - "type": "string", - "description": "Unique identifier for the todo item." - } - } - } - }, - "createdAt": { - "type": "string", - "format": "date-time", - "description": "Timestamp when the session was created." - } - } - } - } - } - } - } - } - }, - "/agent/{domain}/jobs": { - "get": { - "summary": "Get all agent jobs", - "description": "Retrieves all agent jobs for the specified domain, including their status and details.", - "parameters": [ - { - "name": "domain", - "in": "path", - "required": true, - "schema": { - "type": "string" - }, - "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." - } - ], - "responses": { - "200": { - "description": "All agent jobs retrieved successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "allSessions": { - "type": "array", - "description": "Array of all agent sessions for the domain.", - "items": { - "type": "object", - "properties": { - "sessionId": { - "type": "string", - "description": "The subdomain this session belongs to." - }, - "subdomain": { - "type": "string", - "description": "The subdomain this session belongs to." - }, - "branch": { - "type": "string", - "description": "Git branch name where changes were made.", - "nullable": true - }, - "haulted": { - "type": "boolean", - "description": "Whether the session execution was halted." - }, - "haultReason": { - "type": "string", - "enum": ["completed", "github_missconfigured", "error"], - "description": "Reason for session halt." - }, - "pullRequestLink": { - "type": "string", - "description": "Link to the created pull request." - }, - "messageToUser": { - "type": "string", - "description": "Message for the user about the session outcome." - }, - "todos": { - "type": "array", - "description": "List of todo items from the session.", - "items": { - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "Brief description of the task." - }, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "completed", "cancelled"], - "description": "Current status of the task." - }, - "priority": { - "type": "string", - "enum": ["high", "medium", "low"], - "description": "Priority level of the task." - }, - "id": { - "type": "string", - "description": "Unique identifier for the todo item." - } - } - } - }, - "createdAt": { - "type": "string", - "format": "date-time", - "description": "Timestamp when the session was created." - } - } - } - } - } - } - } - } - } - } - } } }, "components": { @@ -871,4 +587,4 @@ } } } -} +} \ No newline at end of file