CardDAV

16 endpoints at a glance

Method	Path	Summary
GET	/carddav/accounts	List Accounts
POST	/carddav/accounts	Create Account
DELETE	/carddav/accounts/{account_id}	Delete Account
PUT	/carddav/accounts/{account_id}	Update Account
GET	/carddav/accounts/{account_id}/addressbooks	List Addressbooks For Account
PUT	/carddav/accounts/{account_id}/addressbooks	Save Addressbooks For Account
GET	/carddav/accounts/{account_id}/addressbooks/available	List Available Addressbooks For Account
POST	/carddav/accounts/{account_id}/set-default	Set Default Account
GET	/carddav/addressbooks	List Addressbooks
PUT	/carddav/addressbooks	Save Addressbooks
GET	/carddav/addressbooks/available	List Available Addressbooks
DELETE	/carddav/connection	Delete Connection
GET	/carddav/connection	Get Connection
PUT	/carddav/connection	Save Connection
POST	/carddav/sync	Sync Now
POST	/carddav/test	Test Connection

carddav

---

Test Connection

POST

/carddav/test

Validate credentials and return discovered addressbooks. Doesn't save.

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"server_url": "string",

  

"username": "string",

  

"password": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/carddav/test

Playground

Headers

authorization

Body

Samples

---

List Accounts

GET

/carddav/accounts

All of the user's CardDAV accounts, default first.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/carddav/accounts

Playground

Headers

authorization

Samples

---

Create Account

POST

/carddav/accounts

Add a NEW CardDAV account. Validates credentials against the server.

Doesn't pick addressbooks — that's a follow-up PUT to
/accounts/{id}/addressbooks.

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"server_url": "string",

  

"username": "string",

  

"password": "string",

  

"label": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/carddav/accounts

Playground

Headers

authorization

Body

Samples

---

Update Account

PUT

/carddav/accounts/{account_id}

Update one account's credentials (validated against the server).

Parameters

Header Parameters

authorization

Path Parameters

account_id*

Type

string

Required

Request Body

application/json

{

  

"server_url": "string",

  

"username": "string",

  

"password": "string",

  

"label": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PUT

/carddav/accounts/{account_id}

Playground

Headers

authorization

Variables

Key

Value

account_id*

Body

Samples

---

Delete Account

DELETE

/carddav/accounts/{account_id}

Remove one account. Cascades its addressbooks (+ contacts, decision (1)).

Parameters

Header Parameters

authorization

Path Parameters

account_id*

Type

string

Required

Query Parameters

delete_contacts

Type

boolean

Default

true

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/carddav/accounts/{account_id}

Playground

Headers

authorization

Variables

Key

Value

account_id*

delete_contacts

Samples

---

Set Default Account

POST

/carddav/accounts/{account_id}/set-default

Make this account the default (the one legacy endpoints act on).

Parameters

Header Parameters

authorization

Path Parameters

account_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/carddav/accounts/{account_id}/set-default

Playground

Headers

authorization

Variables

Key

Value

account_id*

Samples

---

List Available Addressbooks For Account

GET

/carddav/accounts/{account_id}/addressbooks/available

Re-discover one account's addressbooks from its server.

Parameters

Header Parameters

authorization

Path Parameters

account_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/carddav/accounts/{account_id}/addressbooks/available

Playground

Headers

authorization

Variables

Key

Value

account_id*

Samples

---

List Addressbooks For Account

GET

/carddav/accounts/{account_id}/addressbooks

The selected addressbooks belonging to one account.

Parameters

Header Parameters

authorization

Path Parameters

account_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/carddav/accounts/{account_id}/addressbooks

Playground

Headers

authorization

Variables

Key

Value

account_id*

Samples

---

Save Addressbooks For Account

PUT

/carddav/accounts/{account_id}/addressbooks

Set one account's enabled addressbook set (removed books cascade).

Parameters

Header Parameters

authorization

Path Parameters

account_id*

Type

string

Required

Request Body

application/json

{

  

"urls": [

  

  

"string"

  

]

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PUT

/carddav/accounts/{account_id}/addressbooks

Playground

Headers

authorization

Variables

Key

Value

account_id*

Body

Samples

---

Get Connection

GET

/carddav/connection

LEGACY: the default account's connection state (sans password).

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/carddav/connection

Playground

Headers

authorization

Samples

---

Save Connection

PUT

/carddav/connection

LEGACY: save credentials — updates the default account, or creates
the first one. Validates them against the server first.

Doesn't pick addressbooks — that's a follow-up PUT to /addressbooks.

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"server_url": "string",

  

"username": "string",

  

"password": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PUT

/carddav/connection

Playground

Headers

authorization

Body

Samples

---

Delete Connection

DELETE

/carddav/connection

LEGACY: disconnect the user — removes ALL accounts and books.

By default cascades contacts (decision (1)).

Parameters

Header Parameters

authorization

Query Parameters

delete_contacts

Type

boolean

Default

true

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/carddav/connection

Playground

Headers

authorization

Variables

Key

Value

delete_contacts

Samples

---

List Available Addressbooks

GET

/carddav/addressbooks/available

LEGACY: re-discover from the DEFAULT account's server.

Used by the settings UI when the user wants to refresh the picker
after adding a book server-side.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/carddav/addressbooks/available

Playground

Headers

authorization

Samples

---

List Addressbooks

GET

/carddav/addressbooks

All selected addressbooks across every account.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/carddav/addressbooks

Playground

Headers

authorization

Samples

---

Save Addressbooks

PUT

/carddav/addressbooks

LEGACY: set the DEFAULT account's enabled addressbook set.

Decision (1): removed books cascade. Re-discovers from the server so
we know each book's display name and description without trusting
client input.

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"urls": [

  

  

"string"

  

]

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PUT

/carddav/addressbooks

Playground

Headers

authorization

Body

Samples

---

Sync Now

POST

/carddav/sync

Trigger a sync. If addressbook_id is set, only that book.

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"addressbook_id": "string"

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/carddav/sync

Playground

Headers

authorization

Body

Samples

---