Currently, when developing against the API, the only way to give the AI coding agent access to the newest API spec is by copy pasting the info into the context window.
It would be great if the documentation could be served as an MCP server so that the AI coding agent can automatically search the API docs and have up-to-date info on its capabilities.
Might seem obvious, but the actual implementation would not agree with MCP or tool use, as OpenAI so far has only allowed “search query” methods to MCP servers that one could publish on the ChatGPT platform. “conversations” that cannot be edited on the fly are also not good for this, and OpenAI has no insight of actual automated RAG or database use cases for big data in their server-side chat products.
The main impediment is that the YAML API documentation, dereferenced, flattened, and stripped, is 9.5MB. You can put about 1/4th of that into an AI model at once or far less into gpt-5, and then the scope of the knowledge and its distraction from tasks is simply too much to synthesize ideas from beyond haystack searching. The solution would be a database nested retrieval with a TOC that can be tagged, and then you’d also need to teach the AI about MCP itself, independent SDKs and their methods, along with other documentation, then with a drill-down to one programming language.
If you want just an index to provide the AI of where to start grabbing for an injection of text, merely nest level 3 max of the API reference (that barely lists the URL and HTTP methods) is more than twice what I can even post in a forum message after stripping the multi-line block scalars of coding examples. Peruse.
000054 paths:
000055 /assistants:
000056 get:
000057 operationId: listAssistants
000058 tags:
000060 summary: List assistants
000061 parameters:
000092 responses:
000541 x-oaiMeta:
000632 description: Returns a list of assistants.
000633 post:
000634 operationId: createAssistant
000635 tags:
000637 summary: Create assistant
000638 requestBody:
001115 responses:
001481 x-oaiMeta:
001620 description: Create an assistant with a model and instructions.
001621 /assistants/{assistant_id}:
001622 get:
001623 operationId: getAssistant
001624 tags:
001626 summary: Retrieve assistant
001627 parameters:
001634 responses:
002000 x-oaiMeta:
002052 description: Retrieves an assistant.
002053 post:
002054 operationId: modifyAssistant
002055 tags:
002057 summary: Modify assistant
002058 parameters:
002065 requestBody:
002448 responses:
002814 x-oaiMeta:
002890 description: Modifies an assistant.
002891 delete:
002892 operationId: deleteAssistant
002893 tags:
002895 summary: Delete assistant
002896 parameters:
002903 responses:
002925 x-oaiMeta:
002961 description: Delete an assistant.
002962 /audio/speech:
002963 post:
002964 operationId: createSpeech
002965 tags:
002967 summary: Create speech
002968 requestBody:
003049 responses:
003139 x-oaiMeta:
003217 description: Generates audio from the input text.
003218 /audio/transcriptions:
003219 post:
003220 operationId: createTranscription
003221 tags:
003223 summary: Create transcription
003224 requestBody:
003364 responses:
003776 x-oaiMeta:
004214 description: Transcribes audio into the input language.
004215 /audio/translations:
004216 post:
004217 operationId: createTranslation
004218 tags:
004220 summary: Create translation
004221 requestBody:
004272 responses:
004363 x-oaiMeta:
004418 description: Translates audio into English.
004419 /batches:
004420 post:
004421 summary: Create batch
004422 operationId: createBatch
004423 tags:
004425 requestBody:
004500 responses:
004734 x-oaiMeta:
004804 description: Creates and executes a batch from an uploaded file of requests
004805 get:
004806 operationId: listBatches
004807 tags:
004809 summary: List batch
004810 parameters:
004826 responses:
005086 x-oaiMeta:
005155 description: List your organization's batches.
005156 /batches/{batch_id}:
005157 get:
005158 operationId: retrieveBatch
005159 tags:
005161 summary: Retrieve batch
005162 parameters:
005169 responses:
005403 x-oaiMeta:
005461 description: Retrieves a batch.
005462 /batches/{batch_id}/cancel:
005463 post:
005464 operationId: cancelBatch
005465 tags:
005467 summary: Cancel batch
005468 parameters:
005475 responses:
005709 x-oaiMeta:
005768 description: Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10
005771 /chat/completions:
005772 get:
005773 operationId: listChatCompletions
005774 tags:
005776 summary: List Chat Completions
005777 parameters:
005830 responses:
006458 x-oaiMeta:
006522 description: |
006525 post:
006526 operationId: createChatCompletion
006527 tags:
006529 summary: Create chat completion
006530 requestBody:
008119 responses:
009025 x-oaiMeta:
009825 description: "**Starting a new project?** We recommend trying [Responses](https://platform.openai.com/docs/api-reference/responses)\
009834 /chat/completions/{completion_id}:
009835 get:
009836 operationId: getChatCompletion
009837 tags:
009839 summary: Get chat completion
009840 parameters:
009847 responses:
010381 x-oaiMeta:
010438 description: |
010441 post:
010442 operationId: updateChatCompletion
010443 tags:
010445 summary: Update chat completion
010446 parameters:
010453 requestBody:
010477 responses:
011011 x-oaiMeta:
011071 description: |
011075 delete:
011076 operationId: deleteChatCompletion
011077 tags:
011079 summary: Delete chat completion
011080 parameters:
011087 responses:
011112 x-oaiMeta:
011136 description: |
011139 /chat/completions/{completion_id}/messages:
011140 get:
011141 operationId: getChatCompletionMessages
011142 tags:
011144 summary: Get chat messages
011145 parameters:
011176 responses:
011507 x-oaiMeta:
011543 description: |
011547 /completions:
011548 post:
011549 operationId: createCompletion
011550 tags:
011552 summary: Create completion
011553 requestBody:
011786 responses:
011955 x-oaiMeta:
012079 description: Creates a completion for the provided prompt and parameters.
012080 /containers:
012081 get:
012082 summary: List containers
012083 description: List Containers
012084 operationId: ListContainers
012085 parameters:
012110 responses:
012201 x-oaiMeta:
012233 post:
012234 summary: Create container
012235 description: Create Container
012236 operationId: CreateContainer
012237 parameters: []
012238 requestBody:
012270 responses:
012335 x-oaiMeta:
012363 /containers/{container_id}:
012364 get:
012365 summary: Retrieve container
012366 description: Retrieve Container
012367 operationId: RetrieveContainer
012368 parameters:
012374 responses:
012439 x-oaiMeta:
012462 delete:
012463 operationId: DeleteContainer
012464 summary: Delete a container
012465 description: Delete Container
012466 parameters:
012473 responses:
012476 x-oaiMeta:
012492 /containers/{container_id}/files:
012493 post:
012494 summary: Create container file
012495 description: |
012499 operationId: CreateContainerFile
012500 parameters:
012506 requestBody:
012523 responses:
012575 x-oaiMeta:
012597 get:
012598 summary: List container files
012599 description: List Container files
012600 operationId: ListContainerFiles
012601 parameters:
012631 responses:
012708 x-oaiMeta:
012737 /containers/{container_id}/files/{file_id}:
012738 get:
012739 summary: Retrieve container file
012740 description: Retrieve Container File
012741 operationId: RetrieveContainerFile
012742 parameters:
012753 responses:
012805 x-oaiMeta:
012826 delete:
012827 operationId: DeleteContainerFile
012828 summary: Delete a container file
012829 description: Delete Container File
012830 parameters:
012841 responses:
012844 x-oaiMeta:
012860 /containers/{container_id}/files/{file_id}/content:
012861 get:
012862 summary: Retrieve container file content
012863 description: Retrieve Container File Content
012864 operationId: RetrieveContainerFileContent
012865 parameters:
012876 responses:
012879 x-oaiMeta:
012891 /conversations/{conversation_id}/items:
012892 post:
012893 operationId: createConversationItems
012894 tags:
012896 summary: Create items
012897 parameters:
012939 requestBody:
015094 responses:
017089 x-oaiMeta:
017224 description: Create items in a conversation with the given ID.
017225 get:
017226 operationId: listConversationItems
017227 tags:
017229 summary: List items
017230 parameters:
017311 responses:
019306 x-oaiMeta:
019361 description: List all items for a conversation with the given ID.
019362 /conversations/{conversation_id}/items/{item_id}:
019363 get:
019364 operationId: getConversationItem
019365 tags:
019367 summary: Retrieve an item
019368 parameters:
019417 responses:
021372 x-oaiMeta:
021422 description: Get a single item from a conversation with the given IDs.
021423 delete:
021424 operationId: deleteConversationItem
021425 tags:
021427 summary: Delete an item
021428 parameters:
021443 responses:
021475 x-oaiMeta:
021522 description: Delete an item from a conversation with the given IDs.
021523 /embeddings:
021524 post:
021525 operationId: createEmbedding
021526 tags:
021528 summary: Create embeddings
021529 requestBody:
021609 responses:
021687 x-oaiMeta:
021766 description: Creates an embedding vector representing the input text.
021767 /evals:
021768 get:
021769 operationId: listEvals
021770 tags:
021772 summary: List evals
021773 parameters:
021810 responses:
022846 x-oaiMeta:
022944 description: |
022946 post:
022947 operationId: createEval
022948 tags:
022950 summary: Create eval
022951 requestBody:
023777 responses:
024720 x-oaiMeta:
024879 description: |
024883 /evals/{eval_id}:
024884 get:
024885 operationId: getEval
024886 tags:
024888 summary: Get an eval
024889 parameters:
024896 responses:
025839 x-oaiMeta:
025908 description: |
025910 post:
025911 operationId: updateEval
025912 tags:
025914 summary: Update an eval
025915 parameters:
025922 requestBody:
025948 responses:
026891 x-oaiMeta:
026971 description: |
026973 delete:
026974 operationId: deleteEval
026975 tags:
026977 summary: Delete an eval
026978 parameters:
026985 responses:
027031 x-oaiMeta:
027060 description: |
027062 /evals/{eval_id}/runs:
027063 get:
027064 operationId: getEvalRuns
027065 tags:
027067 summary: Get eval runs
027068 parameters:
027112 responses:
029681 x-oaiMeta:
029786 description: |
029788 post:
029789 operationId: createEvalRun
029790 tags:
029792 summary: Create eval run
029793 parameters:
029800 requestBody:
031946 responses:
034421 x-oaiMeta:
034586 description: |
034588 /evals/{eval_id}/runs/{run_id}:
034589 get:
034590 operationId: getEvalRun
034591 tags:
034593 summary: Get an eval run
034594 parameters:
034607 responses:
037057 x-oaiMeta:
037235 description: |
037237 post:
037238 operationId: cancelEvalRun
037239 tags:
037241 summary: Cancel eval run
037242 parameters:
037255 responses:
039705 x-oaiMeta:
039884 description: |
039886 delete:
039887 operationId: deleteEvalRun
039888 tags:
039890 summary: Delete eval run
039891 parameters:
039904 responses:
039946 x-oaiMeta:
039983 description: |
039985 /evals/{eval_id}/runs/{run_id}/output_items:
039986 get:
039987 operationId: getEvalRunOutputItems
039988 tags:
039990 summary: Get eval run output items
039991 parameters:
040039 responses:
040386 x-oaiMeta:
040487 description: |
040489 /evals/{eval_id}/runs/{run_id}/output_items/{output_item_id}:
040490 get:
040491 operationId: getEvalRunOutputItem
040492 tags:
040494 summary: Get an output item of an eval run
040495 parameters:
040514 responses:
040761 x-oaiMeta:
040858 description: |
040860 /files:
040861 get:
040862 operationId: listFiles
040863 tags:
040865 summary: List files
040866 parameters:
040897 responses:
041000 x-oaiMeta:
041055 description: Returns a list of files.
041056 post:
041057 operationId: createFile
041058 tags:
041060 summary: Upload file
041061 requestBody:
041115 responses:
041194 x-oaiMeta:
041249 description: |
041259 /files/{file_id}:
041260 delete:
041261 operationId: deleteFile
041262 tags:
041264 summary: Delete file
041265 parameters:
041272 responses:
041294 x-oaiMeta:
041327 description: Delete a file.
041328 get:
041329 operationId: retrieveFile
041330 tags:
041332 summary: Retrieve file
041333 parameters:
041340 responses:
041419 x-oaiMeta:
041456 description: Returns information about a specific file.
041457 /files/{file_id}/content:
041458 get:
041459 operationId: downloadFile
041460 tags:
041462 summary: Retrieve file content
041463 parameters:
041470 responses:
041477 x-oaiMeta:
041503 description: Returns the contents of the specified file.
041504 /fine_tuning/alpha/graders/run:
041505 post:
041506 operationId: runGrader
041507 tags:
041509 summary: Run grader
041510 requestBody:
042584 responses:
042686 x-oaiMeta:
042762 description: |
042764 /fine_tuning/alpha/graders/validate:
042765 post:
042766 operationId: validateGrader
042767 tags:
042769 summary: Validate grader
042770 requestBody:
043830 responses:
044889 x-oaiMeta:
044919 description: |
044921 /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions:
044922 get:
044923 operationId: listFineTuningCheckpointPermissions
044924 tags:
044926 summary: List checkpoint permissions
044927 parameters:
044965 responses:
045031 x-oaiMeta:
045062 description: |
045066 post:
045067 operationId: createFineTuningCheckpointPermission
045068 tags:
045070 summary: Create checkpoint permissions
045071 parameters:
045080 requestBody:
045096 responses:
045162 x-oaiMeta:
045188 description: |
045192 /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions/{permission_id}:
045193 delete:
045194 operationId: deleteFineTuningCheckpointPermission
045195 tags:
045197 summary: Delete checkpoint permission
045198 parameters:
045215 responses:
045240 x-oaiMeta:
045255 description: |
045259 /fine_tuning/jobs:
045260 post:
045261 operationId: createFineTuningJob
045262 tags:
045264 summary: Create fine-tuning job
045265 requestBody:
046712 responses:
048260 x-oaiMeta:
048664 description: |
048670 get:
048671 operationId: listPaginatedFineTuningJobs
048672 tags:
048674 summary: List fine-tuning jobs
048675 parameters:
048701 responses:
050278 x-oaiMeta:
050330 description: |
050332 /fine_tuning/jobs/{fine_tuning_job_id}:
050333 get:
050334 operationId: retrieveFineTuningJob
050335 tags:
050337 summary: Retrieve fine-tuning job
050338 parameters:
050347 responses:
051895 x-oaiMeta:
051957 description: |
051961 /fine_tuning/jobs/{fine_tuning_job_id}/cancel:
051962 post:
051963 operationId: cancelFineTuningJob
051964 tags:
051966 summary: Cancel fine-tuning
051967 parameters:
051976 responses:
053524 x-oaiMeta:
053563 description: |
053565 /fine_tuning/jobs/{fine_tuning_job_id}/checkpoints:
053566 get:
053567 operationId: listFineTuningJobCheckpoints
053568 tags:
053570 summary: List fine-tuning checkpoints
053571 parameters:
053593 responses:
053698 x-oaiMeta:
053741 description: |
053743 /fine_tuning/jobs/{fine_tuning_job_id}/events:
053744 get:
053745 operationId: listFineTuningEvents
053746 tags:
053748 summary: List fine-tuning events
053749 parameters:
053771 responses:
053848 x-oaiMeta:
053904 description: |
053906 /fine_tuning/jobs/{fine_tuning_job_id}/pause:
053907 post:
053908 operationId: pauseFineTuningJob
053909 tags:
053911 summary: Pause fine-tuning
053912 parameters:
053921 responses:
055469 x-oaiMeta:
055508 description: |
055510 /fine_tuning/jobs/{fine_tuning_job_id}/resume:
055511 post:
055512 operationId: resumeFineTuningJob
055513 tags:
055515 summary: Resume fine-tuning
055516 parameters:
055525 responses:
057073 x-oaiMeta:
057112 description: |
057114 /images/edits:
057115 post:
057116 operationId: createImageEdit
057117 tags:
057119 summary: Create image edit
057120 requestBody:
057307 responses:
057640 x-oaiMeta:
057754 description: Creates an edited or extended image given one or more source images and a prompt. This
057756 /images/generations:
057757 post:
057758 operationId: createImage
057759 tags:
057761 summary: Create image
057762 requestBody:
057939 responses:
058272 x-oaiMeta:
058388 description: |
058390 /images/variations:
058391 post:
058392 operationId: createImageVariation
058393 tags:
058395 summary: Create image variation
058396 requestBody:
058458 responses:
058585 x-oaiMeta:
058646 description: Creates a variation of a given image. This endpoint only supports `dall-e-2`.
058647 /models:
058648 get:
058649 operationId: listModels
058650 tags:
058652 summary: List models
058653 responses:
058706 x-oaiMeta:
058771 description: Lists the currently available models, and provides basic information about each one
058773 /models/{model}:
058774 get:
058775 operationId: retrieveModel
058776 tags:
058778 summary: Retrieve model
058779 parameters:
058787 responses:
058826 x-oaiMeta:
058872 description: Retrieves a model instance, providing basic information about the model such as the
058874 delete:
058875 operationId: deleteModel
058876 tags:
058878 summary: Delete a fine-tuned model
058879 parameters:
058887 responses:
058906 x-oaiMeta:
058942 description: Delete a fine-tuned model. You must have the Owner role in your organization to delete
058944 /moderations:
058945 post:
058946 operationId: createModeration
058947 tags:
058949 summary: Create moderation
058950 requestBody:
059041 responses:
059427 x-oaiMeta:
059652 description: |
059655 /organization/admin_api_keys:
059656 get:
059657 summary: List all organization and project API keys.
059658 operationId: admin-api-keys-list
059659 description: List organization API keys
059660 parameters:
059685 responses:
059802 x-oaiMeta:
059837 post:
059838 summary: Create admin API key
059839 operationId: admin-api-keys-create
059840 description: Create an organization admin API key
059841 requestBody:
059853 responses:
059951 x-oaiMeta:
059983 /organization/admin_api_keys/{key_id}:
059984 get:
059985 summary: Retrieve admin API key
059986 operationId: admin-api-keys-get
059987 description: Retrieve a single organization API key
059988 parameters:
059995 responses:
060093 x-oaiMeta:
060121 delete:
060122 summary: Delete admin API key
060123 operationId: admin-api-keys-delete
060124 description: Delete an organization admin API key
060125 parameters:
060132 responses:
060149 x-oaiMeta:
060165 /organization/audit_logs:
060166 get:
060167 summary: List audit logs
060168 operationId: list-audit-logs
060169 tags:
060171 parameters:
060308 responses:
061129 x-oaiMeta:
061200 description: List user actions and configuration changes within this organization.
061201 /organization/certificates:
061202 get:
061203 summary: List organization certificates
061204 operationId: listOrganizationCertificates
061205 tags:
061207 parameters:
061233 responses:
061325 x-oaiMeta:
061355 description: List uploaded certificates for this organization.
061356 post:
061357 summary: Upload certificate
061358 operationId: uploadCertificate
061359 tags:
061361 requestBody:
061378 responses:
061446 x-oaiMeta:
061472 description: |
061476 /organization/certificates/activate:
061477 post:
061478 summary: Activate certificates for organization
061479 operationId: activateOrganizationCertificates
061480 tags:
061482 requestBody:
061500 responses:
061592 x-oaiMeta:
061634 description: |
061638 /organization/certificates/deactivate:
061639 post:
061640 summary: Deactivate certificates for organization
061641 operationId: deactivateOrganizationCertificates
061642 tags:
061644 requestBody:
061662 responses:
061754 x-oaiMeta:
061796 description: |
061800 /organization/certificates/{certificate_id}:
061801 get:
061802 summary: Get certificate
061803 operationId: getCertificate
061804 tags:
061806 parameters:
061824 responses:
061892 x-oaiMeta:
061914 description: |
061918 post:
061919 summary: Modify certificate
061920 operationId: modifyCertificate
061921 tags:
061923 requestBody:
061937 responses:
062005 x-oaiMeta:
062030 description: |
062032 delete:
062033 summary: Delete certificate
062034 operationId: deleteCertificate
062035 tags:
062037 responses:
062056 x-oaiMeta:
062070 description: |
062074 /organization/costs:
062075 get:
062076 summary: Costs
062077 operationId: usage-costs
062078 tags:
062080 parameters:
062137 responses:
062672 x-oaiMeta:
062707 description: Get costs details for the organization.
062708 /organization/invites:
062709 get:
062710 summary: List invites
062711 operationId: list-invites
062712 tags:
062714 parameters:
062730 responses:
062842 x-oaiMeta:
062871 description: Returns a list of invites in the organization.
062872 post:
062873 summary: Create invite
062874 operationId: inviteUser
062875 tags:
062877 requestBody:
062918 responses:
063004 x-oaiMeta:
063049 description: Create an invite for a user to the organization. The invite must be accepted by the
063051 /organization/invites/{invite_id}:
063052 get:
063053 summary: Retrieve invite
063054 operationId: retrieve-invite
063055 tags:
063057 parameters:
063064 responses:
063150 x-oaiMeta:
063172 description: Retrieves an invite.
063173 delete:
063174 summary: Delete invite
063175 operationId: delete-invite
063176 tags:
063178 parameters:
063185 responses:
063208 x-oaiMeta:
063224 description: Delete an invite. If the invite has already been accepted, it cannot be deleted.
063225 /organization/projects:
063226 get:
063227 summary: List projects
063228 operationId: list-projects
063229 tags:
063231 parameters:
063254 responses:
063331 x-oaiMeta:
063358 description: Returns a list of projects.
063359 post:
063360 summary: Create project
063361 operationId: create-project
063362 tags:
063364 requestBody:
063393 responses:
063447 x-oaiMeta:
063470 description: Create a new project in the organization. Projects can be created and archived, but
063472 /organization/projects/{project_id}:
063473 get:
063474 summary: Retrieve project
063475 operationId: retrieve-project
063476 tags:
063478 parameters:
063485 responses:
063539 x-oaiMeta:
063560 description: Retrieves a project.
063561 post:
063562 summary: Modify project
063563 operationId: modify-project
063564 tags:
063566 parameters:
063573 requestBody:
063587 responses:
063672 x-oaiMeta:
063686 description: Modifies a project in the organization.
063687 /organization/projects/{project_id}/api_keys:
063688 get:
063689 summary: List project API keys
063690 operationId: list-project-api-keys
063691 tags:
063693 parameters:
063715 responses:
063899 x-oaiMeta:
063938 description: Returns a list of API keys in the project.
063939 /organization/projects/{project_id}/api_keys/{key_id}:
063940 get:
063941 summary: Retrieve project API key
063942 operationId: retrieve-project-api-key
063943 tags:
063945 parameters:
063958 responses:
064118 x-oaiMeta:
064149 description: Retrieves an API key in the project.
064150 delete:
064151 summary: Delete project API key
064152 operationId: delete-project-api-key
064153 tags:
064155 parameters:
064168 responses:
064221 x-oaiMeta:
064237 description: Deletes an API key from the project.
064238 /organization/projects/{project_id}/archive:
064239 post:
064240 summary: Archive project
064241 operationId: archive-project
064242 tags:
064244 parameters:
064251 responses:
064305 x-oaiMeta:
064325 description: Archives a project in the organization. Archived projects cannot be used or updated.
064326 /organization/projects/{project_id}/certificates:
064327 get:
064328 summary: List project certificates
064329 operationId: listProjectCertificates
064330 tags:
064332 parameters:
064364 responses:
064456 x-oaiMeta:
064486 description: List certificates for this project.
064487 /organization/projects/{project_id}/certificates/activate:
064488 post:
064489 summary: Activate certificates for project
064490 operationId: activateProjectCertificates
064491 tags:
064493 parameters:
064500 requestBody:
064518 responses:
064610 x-oaiMeta:
064652 description: |
064656 /organization/projects/{project_id}/certificates/deactivate:
064657 post:
064658 summary: Deactivate certificates for project
064659 operationId: deactivateProjectCertificates
064660 tags:
064662 parameters:
064669 requestBody:
064687 responses:
064779 x-oaiMeta:
064821 description: "Deactivate certificates at the project level. You can atomically and \nidempotently\
So “obvious” as useful, but not “obvious” as a path forward to make an AI that can answer all your questions and program a ChatKit session.