supabase/web/docs/guides/api.mdx

---
id: api
title: APIs
description: Auto-generating and Realtime APIs.
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Overview

Supabase generates APIs directly from your database schema. The API is:

- Instant and auto-generated: as you update your database the changes are immediately accessible through your API. 
- Self documenting: Supabase generates documentation in the Dashboard which updates as you make database changes. 
- Secure: the API is configured to work with PostgreSQL's Row Level Security, provisioned behind an API gateway with key-auth enabled. 
- Fast: our benchmarks for basic reads are more than 300% faster than Firebase. The API is a very thin layer on top of Postgres, which does most of the heavy lifting.
- Scalable: the API can serve thousands of simultaneous requests, and works well for Serverless workloads.


### RESTful API 

Supabase provides a RESTful API using [PostgREST](https://postgrest.org/). This is a very thin API layer on top of Postgres. 
It provides everything you need from a CRUD API:

- Basic CRUD operations
- Deeply nested joins, allowing you to fetch data from multiple tables in a single fetch 
- Works with Postgres Views
- Works with Postgres Functions 
- Works with the Postgres security model - including Row Level Security, Roles, and Grants.

<iframe
  className="w-full video-with-border"
  width="640"
  height="385"
  src="https://www.youtube-nocookie.com/embed/rPAJJFdtPw0"
  frameBorder="1"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

### Realtime API

Supabase provides a Realtime API using [Realtime](https://github.com/supabase/realtime). You can use this to listen to database changes over websockets. 
Realtime leverages PostgreSQL's built-in logical replication. You can manage your Realtime API simply by managing Postgres publications.


## Getting started

After you have added tables or functions to your database, you can use the API. 

### Creating API Routes

API routes are automatically created when you create Postgres Tables, Views, or Functions. 

Let's create our first 
API route by creating a table called `todos` (which will store some public user information). 
This will create a corresponding route `todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests.

<Tabs
defaultValue="UI"
values={[
  {label: 'UI', value: 'UI'},
  {label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">

```sh
1. Go to the "Table editor" section.
2. Click "New Table".
3. Enter the table name "todos".
4. Click "Save".
5. Click "New Column".
6. Enter the column name "task" and make the type "text".
7. Click "Save".
```

<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-create-table-sm.mp4" type="video/mp4" muted playsInline />
</video>

</TabItem>
<TabItem value="SQL">

```sql
-- Create a table called "todos" with a column to store tasks.

create table todos (
  id bigint generated by default as identity primary key,
  task text check (char_length(task) > 3)
);
```

</TabItem>
</Tabs>


### API URL and Keys

Every Supabase project has a unique API URL. Your API is secured behind an API gateway which requires an API Key for every request.

You can find the Keys inside the Dashboard.

<Tabs
defaultValue="UI"
values={[
  {label: 'UI', value: 'UI'}
]}>
<TabItem value="UI">

```sh
1. Go to the "Settings" section.
2. Click "API" in the sidebar.
3. Find your API URL in this page.
4. Find your "anon" and "service_role" keys on this page.
```

<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-url-and-key.mp4" type="video/mp4" muted playsInline />
</video>

</TabItem>
</Tabs>


#### Details and links:

You are provided with two keys initially:

- an `anon` key, which is safe to be used in a browser context.
- a `service_role` key, which should only be used on a server. This key can bypass Row Level Security.


### Accessing the Docs

Supabase generates documentation in the Dashboard which updates as you make database changes. 

Let's view the documentation for the `todos` table which we created in the first step.

<Tabs
defaultValue="UI"
values={[
  {label: 'UI', value: 'UI'}
]}>
<TabItem value="UI">

```sh
1. Go to the "API" section.
2. Find "todos" in the "Tables and Views" section.
3. Switch between the Javascript and the cURL docs using the tabs.
```

</TabItem>
</Tabs>


### Using the API

You can interact with your API directly via HTTP requests, or you can use the client libraries which we provide.

Let's see how to make a request to the `todos` table which we created in the first step, 
using the API URL (`[SUPABASE_URL]`) and Key (`[SUPABASE_ANON_KEY]`) we provided:


<Tabs
defaultValue="Javascript"
values={[
  {label: 'Javascript', value: 'Javascript'},
  {label: 'cURL', value: 'cURL'},
]}>
<TabItem value="Javascript">

```javascript
// Initialize the JS client
import { createClient } from '@supabase/supabase-js'
const supabase = createClient([SUPABASE_URL], [SUPABASE_ANON_KEY])

// Make a request
let { data: todos, error } = await supabase
  .from('todos')
  .select('*')
```

</TabItem>
<TabItem value="cURL">

```bash
# Append /rest/v1/ to your URL, and then use the table name as the route
curl '[SUPABASE_URL]/rest/v1/todos' \
-H "apikey: [SUPABASE_ANON_KEY]" \
-H "Authorization: Bearer SUPABASE_ANON_KEY"
```

</TabItem>
</Tabs>

#### Details and links:

- When you create a table in Postgres, Row Level Security is disabled by default. Make sure you secure it by [enabling RLS](/docs/guides/api#securing-your-routes).
- Never expose the `service_role` key in a browser or anywhere where a user can see it.
- JS Reference: [select()](/docs/reference/javascript/select), 
[insert()](/docs/reference/javascript/insert),
[update()](/docs/reference/javascript/update),
[upsert()](/docs/reference/javascript/upsert),
[delete()](/docs/reference/javascript/delete),
[rpc()](/docs/reference/javascript/rpc) (call Postgres functions).


### Managing Realtime 


The Realtime API works through PostgreSQL's replication functionality. Postgres sends database changes to a "publication" 
called `supabase_realtime`, and by managing this publication you can control which data is broadcast.

By default Realtime is disabled on your database. Let's turn on Realtime for the `todos` table.

<Tabs
defaultValue="UI"
values={[
  {label: 'UI', value: 'UI'},
  {label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">

```sh
1. Go to the "Database" section.
2. Click on "Replication" in the sidebar.
3. Control which database events are sent by toggling the Insert/Update/Delete toggles.
4. Control which tables broadcast changes by clicking into the "Source" and toggling the tables.
```

<video width="99%" muted playsInline controls="true">
<source src="/docs/videos/api/api-realtime.mp4" type="video/mp4" muted playsInline />
</video>

</TabItem>
<TabItem value="SQL">

```sql
alter publication supabase_realtime add table products;
```

</TabItem>
</Tabs>

#### Details and links:

- You should only turn on realtime for Public tables (where all data should be accessible). 
- [JS Reference](/docs/reference/javascript/subscribe): Subscribe to database changes using the realtime client


### Securing your Routes 

<Tabs
defaultValue="UI"
values={[
  {label: 'UI', value: 'UI'},
  {label: 'SQL', value: 'SQL'},
]}>
<TabItem value="UI">

```sh
1. Go to the "Authentication" section.
2. Click on "Policies" in the sidebar.
3. Click on the Padlock to enable Row Level Security.
```

</TabItem>
<TabItem value="SQL">

```sql
alter table todos enable row level security;
```

</TabItem>
</Tabs>


#### Details and links:

- Your API is designed to work with Postgres Row Level Security. If you use Supabase [Auth](/docs/guides/auth), you can restrict data based on the logged-in user.
- To control access to your data, you can use [Policies](/docs/guides/auth#policies).