Skip to main content
Dedicated infrastructure only. These endpoints are served by dedicated Enterprise deployments — they are not exposed on the shared public API at api.mixpeek.com, where they return 404/405. See Custom Extractors → Availability. Contact your account team to provision a dedicated deployment.Because this surface isn’t in the shared OpenAPI, it isn’t part of the auto-generated API Reference. This page is the hand-maintained contract; the reference client is server/scripts/api/plugins.py.
Naming. On this surface, custom extractors are addressed as plugins: the path segment is /plugins, and a deployed extractor’s plugin_id is {name}_{version} with dots replaced by underscores — e.g. text_embed@1.0.0 → text_embed_1_0_0. All endpoints are namespace-scoped and take Authorization: Bearer $MIXPEEK_API_KEY.
The CLI (python server/scripts/api/plugins.py push / deploy) wraps these calls. The raw HTTP flow: 
NS=ns_...                 # your namespace id
API=https://<your-dedicated-host>/v1
AUTH=(-H "Authorization: Bearer $MIXPEEK_API_KEY" -H "Content-Type: application/json")

# 1. Request a presigned upload URL (auto-bumps the patch version if you omit it)
UP=$(curl -s -X POST "$API/namespaces/$NS/plugins/uploads" "${AUTH[@]}" \
  -d '{"name":"text_embed","version":"1.0.0","file_size_bytes":5000}')
UPLOAD_ID=$(echo "$UP" | jq -r '.upload_id')
PRESIGNED=$(echo "$UP" | jq -r '.presigned_url')

# 2. PUT the zipped extractor to S3
curl -s -X PUT "$PRESIGNED" -H "Content-Type: application/zip" --data-binary @text_embed.zip

# 3. Confirm — runs the security scan + manifest validation
curl -s -X POST "$API/namespaces/$NS/plugins/uploads/$UPLOAD_ID/confirm" "${AUTH[@]}" \
  -d '{"message":"initial release"}'
# → { "success": true, "plugin_id": "text_embed_1_0_0", "validation_errors": [] }

# 4. Deploy (omit deployment_type for full deploy incl. realtime; batch_only skips the HTTP endpoint)
curl -s -X POST "$API/namespaces/$NS/plugins/text_embed_1_0_0/deploy" "${AUTH[@]}"

# 5. Poll deployment status until DEPLOYED
curl -s "$API/namespaces/$NS/plugins/text_embed_1_0_0/status" "${AUTH[@]}"
Once DEPLOYED, reference the extractor’s feature_uri in a collection’s feature_extractor and in retriever feature_search stages exactly as you would a built-in — see the end-to-end walkthrough.
Deployment statusMeaning
QUEUED / PENDINGWaiting in / triggered the deployment queue
IN_PROGRESSBlue-green rollout in progress
DEPLOYEDReady for real-time inference
NOT_DEPLOYEDBatch-only mode
FAILEDCheck the error field

​
Endpoint reference

All paths are prefixed with /v1/namespaces/{namespace_id}.

​
Upload & deploy

MethodPathPurpose
POST/plugins/uploadsRequest a presigned upload URL. Body: {name, version?, file_size_bytes} → {upload_id, presigned_url, version}
POST/plugins/uploads/{upload_id}/confirmConfirm the S3 upload; runs security scan + manifest validation. Body: {message?} → {success, plugin_id, validation_errors}
POST/pluginsDirect multipart upload (alternative to the presigned flow)
POST/plugins/{plugin_id}/deployDeploy or redeploy. Query: deployment_type=batch_only to skip the realtime endpoint
POST/plugins/{plugin_id}/undeployTear down the deployment (keeps the version)
GET/plugins/{plugin_id}/statusDeployment status
POST/plugins/{plugin_id}/realtime/testInvoke the deployed realtime.py endpoint with a test payload

​
Discover & inspect

MethodPathPurpose
GET/pluginsList custom plugins in the namespace
GET/plugins/{plugin_id}Plugin details (schemas, deployment + validation status)
GET/plugins/{plugin_id}/sourceDownload source files of the active version
GET/plugins/{plugin_id}/downloadPresigned archive download URL
GET/plugins/availableOrg-level plugins available to enable in this namespace

​
Version management

MethodPathPurpose
GET/plugins/by-name/{slug}/versionsVersion history with deploy timestamps + messages
POST/plugins/by-name/{slug}/rollbackRestore a previous version as active
GET/plugins/by-name/{slug}/diff?v1=1.0.0&v2=1.0.1Diff source files between two versions

​
Org plugins & namespace config

MethodPathPurpose
POST/plugins/org/{plugin_id}/enableEnable an org-level plugin in this namespace
POST/plugins/org/{plugin_id}/disableDisable an org-level plugin in this namespace
POST/plugins/reconfigureReconfigure the namespace vector-store schema for a plugin’s features
DELETE/plugins/{plugin_id}Delete a plugin version

​
CLI equivalents

server/scripts/api/plugins.py is the maintained client for this surface (reads MIXPEEK_API_KEY, MIXPEEK_NAMESPACE, MIXPEEK_API_URL):
CLIEndpoint(s)
pushPOST /plugins/uploads → PUT → POST /plugins/uploads/{id}/confirm
pullGET /plugins/by-name/{slug}/versions → GET /plugins/{id}/source
statusGET /plugins/by-name/{slug}/versions
logGET /plugins/by-name/{slug}/versions
rollbackPOST /plugins/by-name/{slug}/rollback
diffGET /plugins/by-name/{slug}/diff
lint / testoffline — no API call (work on any plan)
See Custom Extractors for the full authoring guide and Local Development for lint/test.