What is Tooling API? Provide one example of when you used it.

Posted by Vinay Vernekar 19th November 2025

Overview

The Salesforce Tooling API is a specialized REST (and SOAP) API designed for developers and tools that need fine-grained access to Salesforce metadata, developer-focused objects, and runtime artifacts. It exposes objects and operations that are not available (or are cumbersome) in the Metadata API or standard REST API, making it ideal for building IDE integrations, debug tools, compilers, and automated development workflows.

Key features

The Tooling API provides:

  • Access to developer-focused sObjects such as ApexClass, ApexTrigger, ApexLog, ApexTestQueueItem, and LightningComponentResource.
  • Ability to create/compile Apex classes and triggers, and retrieve compile errors programmatically.
  • Query support with SOQL for tooling sObjects via the /tooling/query/ endpoint.
  • Lightweight operations for IDE-style workflows — save/compile/test — without full metadata deployments.

When to use Tooling API vs Metadata API

Use the Tooling API when you need developer-centric operations (compile on save, retrieve logs, run tests, manage test queue items) or when you require direct access to developer artifacts for real-time IDE feedback. Use the Metadata API for larger, bulk metadata deployments, retrieving full metadata packages, or CI/CD pipelines where package-based deploy/retrieve is required.

Authentication and endpoint

Tooling API uses the same OAuth authentication as other Salesforce APIs. After obtaining an access token, call endpoints under:

/services/data/vXX.X/tooling/

Replace vXX.X with the API version you target (e.g., v58.0).

Example: Common Tooling API calls (curl)

Query Apex classes:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
"https://yourInstance.salesforce.com/services/data/v58.0/tooling/query/?q=SELECT+Id,Name+FROM+ApexClass+WHERE+NamespacePrefix=null"

Create an Apex class (compile-on-save style using Tooling API):

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"Name":"MyTempClass","Body":"public class MyTempClass { public static void hello() { System.debug(\"hi\"); } }"}' \
https://yourInstance.salesforce.com/services/data/v58.0/tooling/sobjects/ApexClass/

Download an Apex debug log body:

curl -L -H "Authorization: Bearer <ACCESS_TOKEN>" \
"https://yourInstance.salesforce.com/services/data/v58.0/tooling/sobjects/ApexLog//Body"

Real-world example — when I used Tooling API

Problem: My team wanted to provide fast, in-editor compile feedback and detailed compile errors when developers edited Apex classes in a custom internal web IDE. Full Metadata deploys were too slow and heavy for an instant “save & compile” experience.

Solution: I used the Tooling API to implement a compile-on-save flow:

  • When a developer saved a class in the IDE, the frontend sent the class name and updated body to a small backend service.
  • The backend authenticated with OAuth and used the Tooling API /sobjects/ApexClass endpoint to create or update the Apex class record. Salesforce automatically compiles the class during that operation.
  • If the compile failed, I queried the ApexCompileError tooling sObject to fetch error messages and line/column details and returned those to the IDE for inline error highlighting.
  • For successful compiles, we ran selected unit tests using ApexTestQueueItem and monitored progress through tooling queries, streaming test results back to the user.

Outcome: Developers got near-instant feedback (seconds rather than minutes), inline editor error markers, and test results — dramatically improving the development experience and reducing context switching.

Tips and pitfalls

  • Rate limits: Tooling API calls count against the org’s API limits; batch operations where possible.
  • Versioning: Use a consistent API version and test across versions when Salesforce updates the API.
  • Permissions: Ensure the OAuth user has appropriate permissions (Modify All Data / Author Apex) for create/compile operations.
  • Use Tooling API for developer workflows; rely on Metadata API or source-driven deployments for full CI/CD pipelines.

Conclusion

The Tooling API is a powerful, targeted API for developer tooling and real-time interactions with Apex, logs, test queues, and other developer artifacts. It’s the right choice when you need fast, granular developer operations that aren’t practical with bulk metadata APIs.

Tags: