canonical: https://jentic.com/apis/pickaxe.co/pickaxe

# Pickaxe API

Jentic publishes the only available OpenAPI specification for Pickaxe API, keeping it validated and agent-ready. Pickaxe provides a platform for creating and managing AI-powered chatbot applications called Pickaxes. The API exposes 5 endpoints for creating new Pickaxe chatbots, updating their configuration, retrieving conversation history, and managing associated knowledge documents. Each Pickaxe is a prompt-based AI application that can be customized with specific instructions, personality, and knowledge base content.

## For AI agents

Create and manage AI chatbot applications on Pickaxe Studio. Build prompt-based chatbots, upload knowledge documents, retrieve chat history, and configure bot behavior programmatically.

## Scope

Does not handle model training, fine-tuning, embedding generation, or direct LLM inference - use for managing pre-built AI chatbot applications and their knowledge bases only.

## Capabilities

- Create new AI chatbot applications with custom prompts, instructions, and personality settings
- Update existing Pickaxe chatbot configurations including prompt text and response behavior
- Retrieve full conversation history from deployed chatbots for analysis and quality monitoring
- Upload and manage knowledge documents that inform chatbot responses
- Configure chatbot parameters including response length, temperature, and fallback behavior

## Use cases

### Custom AI Chatbot Deployment

Create and deploy AI chatbot applications with tailored prompts, personality, and knowledge bases through the Pickaxe platform. Each Pickaxe functions as a standalone conversational AI app that can be embedded on websites or shared via link. The API enables programmatic creation and updates, allowing teams to manage fleets of specialized chatbots for different use cases such as customer support, product recommendations, or internal knowledge assistants.

Example prompt: Create a new Pickaxe chatbot via POST `/studio/pickaxe/create` with a customer support prompt and friendly personality settings

### Knowledge Base Management

Upload and manage documents that serve as the knowledge foundation for Pickaxe chatbots. Documents are processed and indexed so the chatbot can reference them when answering user questions. This enables building domain-specific assistants that draw from company documentation, FAQ sheets, or product manuals without requiring model fine-tuning.

Example prompt: Upload a product FAQ document to Pickaxe ID ABC123 via POST `/studio/pickaxe/{pickaxeId}/documents` to expand the bot's knowledge base

### Conversation Analytics

Retrieve and analyze chat history from deployed Pickaxe chatbots for quality monitoring, user intent analysis, and response improvement. The history endpoint returns full conversation threads including user messages and bot responses, enabling teams to identify common questions, detect response quality issues, and gather training data for prompt refinement.

Example prompt: Retrieve the full chat history via GET `/studio/pickaxe/history`, analyze the last 50 conversations for common user questions, and identify topics where the bot gave unsatisfactory responses

### AI Agent Bot Fleet Management via Jentic

AI agents managing multiple chatbot deployments can create, update, and monitor Pickaxe bots through Jentic without managing bearer tokens directly. The agent searches for chatbot management operations, loads endpoint schemas, and executes bot creation or document uploads with Jentic handling authentication for the Pickaxe Studio platform.

Example prompt: Search Jentic for 'create an AI chatbot', load the Pickaxe create operation, and deploy a new support bot with instructions tailored to a specific product line

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/studio/pickaxe/create` | Create a new AI chatbot application |
| PUT | `/studio/pickaxe/{pickaxeId}` | Update an existing Pickaxe chatbot configuration |
| GET | `/studio/pickaxe/{pickaxeId}` | Retrieve Pickaxe chatbot details and settings |
| GET | `/studio/pickaxe/history` | Retrieve conversation history across chatbots |
| POST | `/studio/pickaxe/{pickaxeId}/documents` | Upload knowledge documents to a Pickaxe |

## Key resources

- **Pickaxes** — Create, update, and retrieve AI chatbot applications with prompt configuration
- **History** — Access conversation logs from deployed chatbots
- **Documents** — Upload and manage knowledge base documents for chatbot responses

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/pickaxe.co/pickaxe/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Pickaxe API by hand means setting up its bearer auth and coding each Studio call to create, update, and load documents into a chatbot yourself. Through Jentic you install once, import Pickaxe from the API Directory, store the bearer token once, and your agent calls it.
- **Permission scoping:** Pickaxe puts the pickaxe id in the URL path (`/studio/pickaxe/{pickaxeId}`), so a rule can pin your agent to one pickaxe: it can read that bot's configuration and add documents to its knowledge base. You choose the operations it may call, so creating new pickaxes or overwriting a bot's configuration is not included unless you add it.
- **Credential handling:** Your Pickaxe bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an AI chatbot' or 'upload knowledge documents to a bot', and Jentic returns the matching Pickaxe operation with its input schema including prompt configuration and document upload fields so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenAI API** — Direct LLM access for custom AI applications beyond Pickaxe's managed platform
- **Cohere API** — RAG and embedding API for advanced knowledge retrieval beyond Pickaxe's document upload
- **Replicate API** — Run open-source AI models via API with more model choice and customization

## FAQ

### Why is there no official OpenAPI spec for Pickaxe API?

Pickaxe does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Pickaxe API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Pickaxe API use?

Pickaxe uses Bearer token authentication. The token is included in the Authorization header for all API requests. Through Jentic, Bearer tokens are stored in your Jentic One instance and injected into requests automatically.

### Can I create a chatbot with a custom knowledge base?

Yes. First create the Pickaxe chatbot via POST `/studio/pickaxe/create` with your prompt instructions, then upload documents to it using POST `/studio/pickaxe/{pickaxeId}/documents.` The chatbot will reference these documents when answering user questions, providing responses grounded in your specific content.

### How do I retrieve conversation logs from a deployed chatbot?

Use GET `/studio/pickaxe/history` to retrieve conversation logs across your chatbots. The endpoint returns full conversation threads including user messages and bot responses, which you can filter and analyze for quality monitoring or prompt improvement.

### How do I deploy a new chatbot through Jentic?

Search Jentic for 'create an AI chatbot application' to find the POST `/studio/pickaxe/create` operation. Load the schema to see configuration options (prompt, personality, response settings), then execute with your desired chatbot parameters. Jentic handles bearer token authentication for the Pickaxe platform.

### Can I limit what my agent is allowed to do with the Pickaxe API?

Yes. Because you run Jentic One yourself, your own rules decide which Pickaxe operations and credentials the agent may use. Since Pickaxe puts the pickaxe id in the URL path (`/studio/pickaxe/{pickaxeId}`), you can pin the agent to a single bot so it only reads that pickaxe's configuration and adds documents to its knowledge base. Creating new pickaxes or overwriting a bot's configuration stays off-limits unless you explicitly grant those operations.