Generate API

The current public API is skill-generation first.

The main backend contract is no longer /query. The current public surface is built around CLI registration, generated skills, reference search, credits, and feedback.

Main Endpoints

Method	Path	Purpose
`POST`	`/cli/register`	Initialize the CLI with a registration key.
`POST`	`/skills/generate`	Generate a custom skill for a task.
`POST`	`/skills/found`	Return ranked reference skills without generating.
`POST`	`/cli/credits`	Return remaining credits for the current session.
`POST`	`/skills/feedback`	Submit execution feedback for a found selection.

POST /cli/register

Initializes a local CLI session from a personal registration key.

json

{
  "registration_key": "ak_live_xxxxx"
}

The CLI wraps this endpoint behind approx init.

POST /skills/generate

This is the main endpoint. It generates a custom skill from a task description.

json

{
  "query": "triage emails and draft replies, then validate the structured output",
  "limit": 5
}

Public response fields:

query
selected_skills
skill_md
generated_skill_id
query_credit when authenticated

POST /skills/found

Returns a ranked shortlist of reference skills without generating a custom skill.

json

{
  "query": "handle customer support email workflow",
  "limit": 5,
  "feedback": true
}

POST /cli/credits

Returns the remaining query credits for the authenticated session.

POST /skills/feedback

Submits feedback after a found skill selection or generated skill was actually used.

Generated Skill Response Example

json

{
  "query": "triage customer emails, draft responses, and schedule follow-ups",
  "selected_skills": [
    {
      "id": "googleworkspace/cli/persona-customer-support",
      "name": "persona-customer-support",
      "source": "googleworkspace/cli",
      "rating": 1800
    },
    {
      "id": "joelhooks/joelclaw/email-triage",
      "name": "email-triage",
      "source": "joelhooks/joelclaw",
      "rating": 1499
    }
  ],
  "skill_md": "# Triage customer emails, draft responses, and schedule follow-ups\n...",
  "generated_skill_id": "gsk_...",
  "query_credit": {
    "remaining": 17
  }
}

CLI Equivalents

bash

approx init <registration_key>
approx generate "handle customer support email workflow"
approx find "handle customer support email workflow"
approx credits
approx feedback --file feedback.json

The CLI is the preferred public entry point. Use raw HTTP only when you are integrating Approxination directly into your own runtime.