Openai Port

Purpose

This is the reference integration for Harbor http_api Action Model authoring for OpenAI.

Use it when:

• building OpenAI actions in Harbor
• extending the Dock / Hub OpenAI entry
• teaching Codex or OpenClaw how to map a model API into Harbor Ports and Harbor Actions

Harbor Port worksheet

Product

• Product: OpenAI API
• Publisher slug: openai
• Publisher name: OpenAI
• Category: AI
• Tags: openai, ai, llm, responses, embeddings, vector-stores, fine-tuning, batches

Safe Harbor Port metadata

• Kind: http_api
• Label: OpenAI API
• Description: OpenAI API connection managed locally through Harbor.
• Base URL: https://api.openai.com/v1/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

OpenAI is a good Harbor fit when we stay on fixed v1 routes, keep variable identifiers in typed input.path values, and keep prompts or payloads inside input.body.

Good Harbor OpenAI actions:

• stable GET and DELETE routes like /models/{model} or /files/{file_id}
• fixed POST routes like /responses, /embeddings, /vector_stores, /fine_tuning/jobs, and /batches
• requestBodyMode: "none" for reads and bodyless state changes
• requestBodyMode: "json" for prompt-bearing, search, and create or update calls
• resultMode: "json_summary" for all imported actions

Keep approval on by default for model execution and for state-changing operations. Responses, embeddings, vector-store search, images, uploads, batches, and fine-tuning calls are billable or operationally sensitive and are better treated as reviewed capabilities.

Still avoid for now:

• multipart-only flows such as file upload creation, upload parts, image edit or variation, and audio transcription or translation
• realtime and websocket-specific flows
• organization admin endpoints
• arbitrary hidden-header expansion beyond the current Harbor auth model

Imported OpenAI actions

Automatic read actions

• list-models -> GET /models
• get-model -> GET /models/{model}
• get-response -> GET /responses/{response_id}
• list-response-input-items -> GET /responses/{response_id}/input_items
• list-files -> GET /files
• get-file -> GET /files/{file_id}
• get-file-content -> GET /files/{file_id}/content
• list-batches -> GET /batches
• get-batch -> GET /batches/{batch_id}
• list-vector-stores -> GET /vector_stores
• get-vector-store -> GET /vector_stores/{vector_store_id}
• list-fine-tuning-jobs -> GET /fine_tuning/jobs
• get-fine-tuning-job -> GET /fine_tuning/jobs/{fine_tuning_job_id}
• list-fine-tuning-events -> GET /fine_tuning/jobs/{fine_tuning_job_id}/events
• list-fine-tuning-checkpoints -> GET /fine_tuning/jobs/{fine_tuning_job_id}/checkpoints

Approval-friendly write actions

• delete-fine-tuned-model -> DELETE /models/{model}
• create-response -> POST /responses
• delete-response -> DELETE /responses/{response_id}
• cancel-response -> POST /responses/{response_id}/cancel
• compact-response -> POST /responses/compact
• count-response-input-tokens -> POST /responses/input_tokens
• create-embedding -> POST /embeddings
• create-image -> POST /images/generations
• create-speech -> POST /audio/speech
• create-moderation -> POST /moderations
• create-completion -> POST /completions
• delete-file -> DELETE /files/{file_id}
• create-batch -> POST /batches
• cancel-batch -> POST /batches/{batch_id}/cancel
• create-upload -> POST /uploads
• complete-upload -> POST /uploads/{upload_id}/complete
• cancel-upload -> POST /uploads/{upload_id}/cancel
• create-vector-store -> POST /vector_stores
• update-vector-store -> POST /vector_stores/{vector_store_id}
• delete-vector-store -> DELETE /vector_stores/{vector_store_id}
• search-vector-store -> POST /vector_stores/{vector_store_id}/search
• create-fine-tuning-job -> POST /fine_tuning/jobs
• cancel-fine-tuning-job -> POST /fine_tuning/jobs/{fine_tuning_job_id}/cancel
• pause-fine-tuning-job -> POST /fine_tuning/jobs/{fine_tuning_job_id}/pause
• resume-fine-tuning-job -> POST /fine_tuning/jobs/{fine_tuning_job_id}/resume

Why these actions

These routes fit Harbor's Action Model well because they:

• stay under one fixed OpenAI API origin
• use stable, documented v1 paths with typed identifiers
• keep prompts and payloads inside explicit JSON request bodies
• can be reviewed as named capabilities
• keep hidden auth entirely local to Harbor Node

Suggested operator workflow

1. Import the OpenAI Dock entry from Dock / Hub.
2. Configure the local OpenAI API key in Harbor Node.
3. Validate list-models first to confirm local auth.
4. Keep prompt-bearing and state-changing actions on require_approval unless there is a deliberate local policy reason not to.
5. Keep multipart and realtime-only flows separate until Harbor grows first-class support for them.

Suggested agent workflow

1. Inspect the existing OpenAI Harbor Port.
2. Inspect live actions and drafts.
3. Propose only fixed-route, Harbor-safe additions that match the current auth and body model.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored API key
• widen OpenAI into a generic arbitrary HTTP proxy
• bypass approval for prompt-bearing actions without operator intent

Current update strategy

For now, OpenAI updates are manual:

• update the Dock / Hub integration document in apps/hub/catalog/integrations/openai/openai-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• OpenAI API overview: https://developers.openai.com/api/reference/overview
• OpenAI models list: https://developers.openai.com/api/reference/resources/models/methods/list
• OpenAI responses resource: https://developers.openai.com/api/reference/resources/responses
• OpenAI embeddings create: https://developers.openai.com/api/reference/resources/embeddings/methods/create
• OpenAI files resource: https://developers.openai.com/api/reference/resources/files
• OpenAI images resource: https://developers.openai.com/api/reference/resources/images
• OpenAI moderations resource: https://developers.openai.com/api/reference/resources/moderations
• OpenAI batches resource: https://developers.openai.com/api/reference/resources/batches
• OpenAI uploads resource: https://developers.openai.com/api/reference/resources/uploads
• OpenAI vector stores resource: https://developers.openai.com/api/reference/resources/vector_stores
• OpenAI fine-tuning resource: https://developers.openai.com/api/reference/resources/fine_tuning