Platform
Grounding your AI coding assistant: the Apex Symbol API in Winter '27
Your AI assistant writes Apex that looks right and fails to compile, because it pattern-matched on common Salesforce names instead of reading your org's real types. The fix is feeding it compiler-grade metadata. Here's why the hallucination happens, what the SymbolTable already gives you, and what the Winter '27 Apex Symbol API adds.
The tell is always the same. Your AI assistant hands you a clean-looking Apex class, you save it, and the compiler rejects a method that does not exist. A Messaging call with the wrong name. A field the model was sure lived on the object. A signature that was right two API versions ago.
The code reads as confident and correct. None of it survives contact with your org.
The model is not being careless; it is reading the wrong source. An assistant that never queried your org guesses at your types from a million public Salesforce examples, so the guess imitates Apex rather than matching yours. The fix is not a better model. The fix is grounding: giving the assistant your org’s real type metadata so it stops inventing.
Winter ‘27 adds a first-party piece to that story, the Apex Symbol API. Before you reach for it, it helps to see exactly what the model gets wrong, and what your org could already tell it.
Why the hallucination happens
A language model writes Apex by predicting the next token from patterns it saw in training. It has read a great deal of Apex, so it is fluent in the standard library’s rhythm and the common idioms. What it never read is your org: your custom objects, your fields, your managed-package namespaces, the wrapper class a predecessor wrote in 2021.
So it fills the gap with the most probable token. Ask it to send an email and it reaches for a Messaging method that sounds plausible. If the real method has a different name or argument list, the model has no way to know, because it never had the definitive list in front of it.
The same failure hits your own code. Paste a class into the prompt and the assistant calls it correctly, because now it can read the definition. Leave that class out and it invents the method it wishes you had written.
That asymmetry is the whole game. A model is accurate about what it can read and confabulates about everything else. Grounding is the work of shrinking the “everything else.”
A model hallucinates in exact proportion to what you have hidden from it. Grounding is not a model upgrade. It hands the model the definitions it was otherwise forced to guess.
What your org can already tell it
You do not need Winter ‘27 to start. The Tooling API has exposed a structured view of a class’s types for years, through the SymbolTable on the ApexClass object. A single Tooling query returns it:
GET /services/data/v68.0/tooling/query/?q=SELECT+Name,SymbolTable+FROM+ApexClass+WHERE+Name='InvoiceService'
Authorization: Bearer <access_token>The SymbolTable describes the user-defined tokens in that class: its methods with their parameters and return types, its properties, its inner classes, and the external references it makes. Feed that JSON into an assistant’s context and it stops guessing at the shape of InvoiceService. It has the signatures instead of a statistical impression of them.
The ceiling sits there too. A SymbolTable describes what a class contains, and stays thin on what it calls into, where the standard library and other packages are where most hallucinations live.
The model rarely invents a method on a class you wrote and handed it. It invents methods on Messaging, on Database, on EncodingUtil, the platform surface it cannot enumerate from one class’s table. Closing that gap by hand means bolting an Apex grammar parser onto your tooling and maintaining a type index yourself, which is a project nobody wants to own.
You may have met the other half of this already. The Salesforce DX MCP server lets a tool like Claude Code or Cursor run SOQL, deploy metadata, and execute Apex tests against a specific org. The official Claude Code plugin wires those servers in with skills and deploy gates.
Both give the agent a way to act on your org. Neither, on its own, gives it a compiler-grade map of every type it might reference before it writes a line. That map is the piece Winter ‘27 aims at.
What the Apex Symbol API adds
The Apex Symbol API arrives in Winter ‘27 (API version 68.0) as a Tooling API resource that returns metadata about Apex types, scoped wider than the per-class SymbolTable. Reporting across the release describes it as covering built-in, custom, and dynamic types rather than only the tokens inside one class you named.
That wider scope is the difference that matters for grounding: a route to the type definitions your code calls into, beyond the code you wrote yourself.
Salesforce’s stated purpose is not subtle. The feature is positioned for powering code completion in IDEs, providing context for AI agents that work with Apex, and grounding the agents that answer questions about Apex code. Salesforce is describing the same anti-hallucination job, promoted from a homegrown workaround to a first-party API.
A few honest caveats, because this is going into how you build. The Symbol API is landing as a beta, and Salesforce beta features can change shape between releases, so treat its response format as provisional rather than a contract. Reporting also puts its early availability in sandboxes, Developer Editions, and scratch orgs rather than production.
I could not confirm the exact resource path or the response schema against the live Tooling API guide from where I sit. Pull the Winter ‘27 Tooling API developer guide for 68.0 and read the resource definition there before you code against it. What is safe to build on today is the pattern: a Tooling API call that returns type metadata you inject into an assistant’s context. The Symbol API widens what that call can return. It does not change the shape of the technique.
How to wire grounding into the workflow
Grounding is a retrieval step you insert before generation. The mechanics stay the same whether the metadata comes from a SymbolTable today or the Symbol API tomorrow.
The cleanest place to put it is an MCP tool. If your assistant already talks to the org through an MCP server, add a tool whose job is “given a type name, return its metadata,” backed by a Tooling query. The agent calls it while planning, gets exact signatures, and writes against them.
That keeps the type data out of a stale prompt and fresh on every request, which matters because your org changes. A metadata snapshot pasted last week becomes its own source of wrong answers.
The retrieval discipline mirrors what makes any grounded agent trustworthy rather than guessing: give the model the specific definitions the task needs, not a data dump. Ten thousand tokens of every type in the org buries the three signatures that matter and slows the response. Fetch the types named in the task, their direct dependencies, and stop.
A useful habit is to make the assistant show its work. Ask it to name the types and methods it is about to call before it writes the body, then check that list against what the metadata tool returned. A method that appears in the plan but not in the org’s type data is a hallucination you caught before a compile, which is far cheaper than catching it after.
Grounding narrows the risk, it does not close it
A grounded assistant invents fewer methods. It does not write safe Apex on its own. Compiler-grade type data tells the model that Database.query exists and what it takes. It says nothing about whether the query respects field-level security, runs inside a loop, or trusts user input.
Those are the failures that pass compilation and fail in production, or in front of a security reviewer.
So the review gate stays. Everything an assistant produces goes through the scrutiny you would give a fast junior developer’s pull request: CRUD and FLS enforcement, bulk-safety, governor-limit headroom, injection surface. The AppExchange Security Review checks that bar, and it is worth running AI-written Apex through the Apex Security Scanner before it reaches a shared branch.
Generated code that ships without that pass is how technical debt compounds faster than a team can pay it down. The point of grounding is to spend your review attention on logic and security, not on chasing methods that were never real.
The rest of the Winter ‘27 developer drop, in one breath
The Symbol API ships alongside changes that touch the same audience. Apex heap limits rise, synchronous from 6 MB to 10 MB and asynchronous from 12 MB to 25 MB, applied on your upgrade date. That relieves a specific class of large-payload work without being a reason to abandon slicing.
@IntegrationTest classes that make real HTTP callouts in a scratch org expand in developer preview to any endpoint, where the earlier release allowed only the Agentforce and Data 360 ones. Both are worth reading in the full Winter ‘27 practitioner cut before your instance upgrades, because the release updates in that post are the ones that break integrations if you ignore them.
What I would do
Start grounding before the Symbol API is even GA, because the technique pays off with the tools you already have. Stand up a metadata-retrieval tool backed by the SymbolTable for your own classes, wire it into whatever AI client your team uses, and make the assistant consult it before it writes. You will watch the invented-method rate drop the first afternoon.
Then track the Symbol API through the release notes as it moves from beta toward production, and swap it in behind that same tool once it covers the platform surface your homemade index never fully will. The interface your developers touch does not change. What changes is how little the model has left to guess about.
Understanding the basics
What is the Apex Symbol API?
The Apex Symbol API is a Tooling API resource introduced in the Salesforce Winter ‘27 release (API version 68.0) that returns metadata about Apex types, reported to cover built-in, custom, and dynamic types rather than only the tokens inside a single class. Salesforce positions it for code completion in IDEs and for grounding AI agents that read or write Apex, so an assistant can work from exact, compiler-resolved type information instead of guessing. The API is arriving as a beta, so confirm its status, availability, and response format against the current Tooling API developer guide before building on it.
Why does my AI assistant invent Apex methods and fields that don’t exist?
Because it predicts plausible code from patterns it saw in training, not from reading your org. The assistant is accurate about any class or object definition you put in front of it and confabulates about everything you leave out, which is why it most often invents methods on the standard library and on managed packages it cannot enumerate. Feeding it your org’s real type metadata, through the Tooling API’s SymbolTable today or the Apex Symbol API as it matures, is what closes the gap.
Is the Apex Symbol API generally available?
As of Winter ‘27 it is reported to be in beta, with early availability in sandboxes, Developer Editions, and scratch orgs rather than production. Beta features can change between releases and are not covered by Salesforce’s usual backward-compatibility guarantees, so treat the response format as provisional and re-check the release notes before you depend on it in a build.
How is it different from the SymbolTable on ApexClass?
The SymbolTable field on the ApexClass Tooling API object describes the user-defined tokens inside one class you query: its methods, properties, inner classes, and external references. The table stays thin on the definitions of the platform and package types that class calls into, which is where most hallucinations occur. The Apex Symbol API is described as covering built-in, custom, and dynamic types more broadly, giving a route to that wider type surface without maintaining your own Apex parser and index.
Rolling out an AI coding workflow on Salesforce and want it grounded and gated before it touches an org, not after? Talk to us. Building to the engineering bar the Security Review checks, with AI in the loop rather than in charge, is the work we do.
