> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tree-sitter/tree-sitter/llms.txt
> Use this file to discover all available pages before exploring further.

# C API overview

> Overview of the Tree-sitter C API for parsing and syntax tree manipulation

The Tree-sitter C API provides a complete interface for parsing source code and working with syntax trees. This API is the foundation for all Tree-sitter language bindings and provides fine-grained control over parsing operations.

## Core components

The C API is organized into several main components:

* **[Parser](/api/c-api/parser)** - Create parsers, configure parsing options, and parse source code
* **[Tree](/api/c-api/tree)** - Work with syntax trees, including copying, editing, and comparing trees
* **[Node](/api/c-api/node)** - Inspect and traverse syntax tree nodes
* **[Query](/api/c-api/query)** - Create and execute queries to search for patterns in syntax trees
* **[Language](/api/c-api/language)** - Access language-specific information and metadata

## Key types

The API uses several opaque pointer types:

* `TSParser` - A parser instance
* `TSTree` - A syntax tree
* `TSNode` - A node in a syntax tree (passed by value)
* `TSQuery` - A compiled query
* `TSLanguage` - A language definition

## ABI versioning

Tree-sitter uses ABI versioning to ensure compatibility between the library and language parsers:

```c theme={null}
#define TREE_SITTER_LANGUAGE_VERSION 15
#define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 13
```

Languages generated by the Tree-sitter CLI are assigned an ABI version. The library is generally backwards-compatible with older versions but not forwards-compatible.

## Memory management

The C API follows these memory management conventions:

* Functions ending in `_new` allocate memory that must be freed with the corresponding `_delete` function
* Functions returning `const char *` return pointers to memory owned by Tree-sitter (do not free)
* Functions returning `char *` return memory allocated with `malloc` that the caller must free
* Arrays returned with a length parameter are typically owned by the caller and must be freed

## Basic usage example

```c theme={null}
#include <tree_sitter/api.h>

// Declare the language function
const TSLanguage *tree_sitter_c(void);

int main() {
  // Create a parser
  TSParser *parser = ts_parser_new();
  
  // Set the language
  ts_parser_set_language(parser, tree_sitter_c());
  
  // Parse some source code
  const char *source_code = "int main() { return 0; }";
  TSTree *tree = ts_parser_parse_string(
    parser,
    NULL,
    source_code,
    strlen(source_code)
  );
  
  // Get the root node
  TSNode root_node = ts_tree_root_node(tree);
  
  // Print the syntax tree
  char *string = ts_node_string(root_node);
  printf("Syntax tree: %s\n", string);
  free(string);
  
  // Clean up
  ts_tree_delete(tree);
  ts_parser_delete(parser);
  
  return 0;
}
```

## Thread safety

Syntax trees are not thread-safe. To use a tree on multiple threads:

1. Create a shallow copy with `ts_tree_copy` for each thread
2. Each thread can safely read from its own copy
3. Delete each copy when done

Parsers are also not thread-safe and should not be shared between threads.

## Error handling

Most Tree-sitter functions indicate errors through return values:

* Functions returning pointers return `NULL` on error
* Functions returning `bool` return `false` on error
* Query functions write error information to output parameters