Skip to content

Commit 4e914ef

Browse files
mintlify-development[bot]mintlify[bot]cdxker
authored
Update api-discovery endpoint to admin api (#1407)
* Update api-reference/agent/create-agent-job.mdx * Update api-reference/agent/get-agent-job.mdx * Update api-reference/agent/get-all-jobs.mdx * Update api-reference/introduction.mdx * Update api-reference/introduction.mdx * Update discovery-openapi.json * Update discovery-openapi.json * Update admin-openapi.json * Update api-reference/agent/create-agent-job.mdx * feature: fix route, add details api key * feature: rename domain / projectId plus copy --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: mintlify-development[bot] <109878554+mintlify-development[bot]@users.noreply.github.com> Co-authored-by: cdxker <[email protected]>
1 parent 70a63ae commit 4e914ef

File tree

6 files changed

+367
-293
lines changed

6 files changed

+367
-293
lines changed

‎admin-openapi.json‎

Lines changed: 357 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,357 @@
1+
{
2+
"openapi": "3.0.1",
3+
"info": {
4+
"title": "Mintlify Admin API",
5+
"description": "An API for administrative operations including documentation updates and agent management.",
6+
"version": "1.0.0"
7+
},
8+
"servers": [
9+
{
10+
"url": "https://api.mintlify.com/v1"
11+
}
12+
],
13+
"security": [
14+
{
15+
"bearerAuth": []
16+
}
17+
],
18+
"paths": {
19+
"/admin/update/{domain}": {
20+
"post": {
21+
"summary": "Trigger update",
22+
"description": "Triggers an update of your documentation site.",
23+
"parameters": [
24+
{
25+
"name": "domain",
26+
"in": "path",
27+
"required": true,
28+
"schema": {
29+
"type": "string"
30+
},
31+
"description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard."
32+
}
33+
],
34+
"responses": {
35+
"200": {
36+
"description": "Update triggered successfully"
37+
}
38+
}
39+
}
40+
},
41+
"/admin/update/{domain}/status": {
42+
"get": {
43+
"summary": "Get update status",
44+
"description": "Retrieves the status of documentation updates and other details about your docs.",
45+
"parameters": [
46+
{
47+
"name": "domain",
48+
"in": "path",
49+
"required": true,
50+
"schema": {
51+
"type": "string"
52+
},
53+
"description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard."
54+
}
55+
],
56+
"responses": {
57+
"200": {
58+
"description": "Update status retrieved successfully"
59+
}
60+
}
61+
}
62+
},
63+
"/agent/job/{projectId}": {
64+
"post": {
65+
"summary": "Create agent job",
66+
"description": "Creates a new agent job that can generate and edit documentation based on provided messages and branch information.",
67+
"parameters": [
68+
{
69+
"name": "projectId",
70+
"in": "path",
71+
"required": true,
72+
"schema": {
73+
"type": "string"
74+
},
75+
"description": "The ID of your project. Can be retrieved from your dashboard."
76+
}
77+
],
78+
"requestBody": {
79+
"required": true,
80+
"content": {
81+
"application/json": {
82+
"schema": {
83+
"type": "object",
84+
"required": [
85+
"branch",
86+
"messages"
87+
],
88+
"properties": {
89+
"branch": {
90+
"type": "string",
91+
"description": "The name of the Git branch that the agent should work on, will be automatically created if it doesn't exist"
92+
},
93+
"messages": {
94+
"type": "array",
95+
"description": "A list of previous messages to provide to the agent.",
96+
"items": {
97+
"type": "object",
98+
"required": [
99+
"role",
100+
"content"
101+
],
102+
"properties": {
103+
"role": {
104+
"type": "string",
105+
"enum": ["system", "user"],
106+
"description": "The role of the message sender."
107+
},
108+
"content": {
109+
"type": "string",
110+
"description": "The content of the message."
111+
}
112+
}
113+
}
114+
}
115+
}
116+
}
117+
}
118+
}
119+
},
120+
"responses": {
121+
"200": {
122+
"description": "Agent job created successfully (streaming response). X-Session-Id Header is sent back in the response",
123+
"headers": {
124+
"X-Message-Id": {
125+
"schema": {
126+
"type": "string"
127+
},
128+
"description": "Message identifier for the created job"
129+
}
130+
},
131+
"content": {
132+
"text/plain": {
133+
"schema": {
134+
"type": "string",
135+
"description": "Streaming response containing the agent job execution details and results."
136+
}
137+
}
138+
}
139+
}
140+
}
141+
}
142+
},
143+
"/agent/{projectId}/job/{id}": {
144+
"get": {
145+
"summary": "Get agent job by ID",
146+
"description": "Retrieves the details and status of a specific agent job by its ID.",
147+
"parameters": [
148+
{
149+
"name": "projectId",
150+
"in": "path",
151+
"required": true,
152+
"schema": {
153+
"type": "string"
154+
},
155+
"description": "The ID of your project. Can be retrieved from your dashboard."
156+
},
157+
{
158+
"name": "id",
159+
"in": "path",
160+
"required": true,
161+
"schema": {
162+
"type": "string"
163+
},
164+
"description": "The unique identifier of the agent job to retrieve."
165+
}
166+
],
167+
"responses": {
168+
"200": {
169+
"description": "Agent job details retrieved successfully",
170+
"content": {
171+
"application/json": {
172+
"schema": {
173+
"type": "object",
174+
"properties": {
175+
"sessionId": {
176+
"type": "string",
177+
"description": "The subdomain this session belongs to."
178+
},
179+
"subdomain": {
180+
"type": "string",
181+
"description": "The subdomain this session belongs to."
182+
},
183+
"branch": {
184+
"type": "string",
185+
"description": "Git branch name where changes were made.",
186+
"nullable": true
187+
},
188+
"haulted": {
189+
"type": "boolean",
190+
"description": "Whether the session execution was halted."
191+
},
192+
"haultReason": {
193+
"type": "string",
194+
"enum": ["completed", "github_missconfigured", "error"],
195+
"description": "Reason for session halt."
196+
},
197+
"pullRequestLink": {
198+
"type": "string",
199+
"description": "Link to the created pull request."
200+
},
201+
"messageToUser": {
202+
"type": "string",
203+
"description": "Message for the user about the session outcome."
204+
},
205+
"todos": {
206+
"type": "array",
207+
"description": "List of todo items from the session.",
208+
"items": {
209+
"type": "object",
210+
"properties": {
211+
"content": {
212+
"type": "string",
213+
"description": "Brief description of the task."
214+
},
215+
"status": {
216+
"type": "string",
217+
"enum": ["pending", "in_progress", "completed", "cancelled"],
218+
"description": "Current status of the task."
219+
},
220+
"priority": {
221+
"type": "string",
222+
"enum": ["high", "medium", "low"],
223+
"description": "Priority level of the task."
224+
},
225+
"id": {
226+
"type": "string",
227+
"description": "Unique identifier for the todo item."
228+
}
229+
}
230+
}
231+
},
232+
"createdAt": {
233+
"type": "string",
234+
"format": "date-time",
235+
"description": "Timestamp when the session was created."
236+
}
237+
}
238+
}
239+
}
240+
}
241+
}
242+
}
243+
}
244+
},
245+
"/agent/{projectId}/jobs": {
246+
"get": {
247+
"summary": "Get all agent jobs",
248+
"description": "Retrieves all agent jobs for the specified domain, including their status and details.",
249+
"parameters": [
250+
{
251+
"name": "projectId",
252+
"in": "path",
253+
"required": true,
254+
"schema": {
255+
"type": "string"
256+
},
257+
"description": "The ID of your project. Can be retrieved from your dashboard."
258+
}
259+
],
260+
"responses": {
261+
"200": {
262+
"description": "All agent jobs retrieved successfully",
263+
"content": {
264+
"application/json": {
265+
"schema": {
266+
"type": "object",
267+
"properties": {
268+
"allSessions": {
269+
"type": "array",
270+
"description": "Array of all agent sessions for the domain.",
271+
"items": {
272+
"type": "object",
273+
"properties": {
274+
"sessionId": {
275+
"type": "string",
276+
"description": "The subdomain this session belongs to."
277+
},
278+
"subdomain": {
279+
"type": "string",
280+
"description": "The subdomain this session belongs to."
281+
},
282+
"branch": {
283+
"type": "string",
284+
"description": "Git branch name where changes were made.",
285+
"nullable": true
286+
},
287+
"haulted": {
288+
"type": "boolean",
289+
"description": "Whether the session execution was halted."
290+
},
291+
"haultReason": {
292+
"type": "string",
293+
"enum": ["completed", "github_missconfigured", "error"],
294+
"description": "Reason for session halt."
295+
},
296+
"pullRequestLink": {
297+
"type": "string",
298+
"description": "Link to the created pull request."
299+
},
300+
"messageToUser": {
301+
"type": "string",
302+
"description": "Message for the user about the session outcome."
303+
},
304+
"todos": {
305+
"type": "array",
306+
"description": "List of todo items from the session.",
307+
"items": {
308+
"type": "object",
309+
"properties": {
310+
"content": {
311+
"type": "string",
312+
"description": "Brief description of the task."
313+
},
314+
"status": {
315+
"type": "string",
316+
"enum": ["pending", "in_progress", "completed", "cancelled"],
317+
"description": "Current status of the task."
318+
},
319+
"priority": {
320+
"type": "string",
321+
"enum": ["high", "medium", "low"],
322+
"description": "Priority level of the task."
323+
},
324+
"id": {
325+
"type": "string",
326+
"description": "Unique identifier for the todo item."
327+
}
328+
}
329+
}
330+
},
331+
"createdAt": {
332+
"type": "string",
333+
"format": "date-time",
334+
"description": "Timestamp when the session was created."
335+
}
336+
}
337+
}
338+
}
339+
}
340+
}
341+
}
342+
}
343+
}
344+
}
345+
}
346+
}
347+
},
348+
"components": {
349+
"securitySchemes": {
350+
"bearerAuth": {
351+
"type": "http",
352+
"scheme": "bearer",
353+
"description": "The Authorization header expects a Bearer token. Create an [Admin API Key](https://dashboard.mintlify.com/settings/organization/api-keys) here."
354+
}
355+
}
356+
}
357+
}

‎api-reference/agent/create-agent-job.mdx‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
openapi: POST /agent/job/{domain}
2+
openapi: POST /agent/job/{projectId}
33
---
44

55
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
1010

1111
The agent API has the following limits:
1212

13-
- 10,000 uses per key per month
14-
- 10,000 requests per Mintlify organization per hour
15-
- 10,000 requests per IP per day
13+
- 100 uses per Mintlify project per hour
1614

1715
## Suggested usage
1816

‎api-reference/agent/get-agent-job.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
openapi: GET /agent/{domain}/job/{id}
2+
openapi: GET /agent/{projectId}/job/{id}
33
---
44

55
## Usage

‎api-reference/agent/get-all-jobs.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
openapi: GET /agent/{domain}/jobs
2+
openapi: GET /agent/{projectId}/jobs
33
---
44

55
## Usage

0 commit comments

Comments
 (0)