Cozy Cloudery (1.0.0)

Download OpenAPI specification:Download

E-mail: contact@cozycloud.cc License: GFDL-1.3

Cozy Cloudery controls Cozy instances life cycle, like creation, deletion, premium features…

Authentication

token

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

instances

A Cozy instance is the personnal space for a user where they can save their files and documents.

onboard

Start onboarding process for an instance creation. This is not an API endpoint, but an URL where the user can go in order to create their Cozy. It will redirect to an HTML page where the user can type/confirm their email address.

path Parameters

partner

required

string

Example: cozy

query Parameters

offer	string Example: offer=cozy_default
slug	string ^[a-z][a-z0-9]{0,29}$ Example: slug=somecozy Default slug to propose to user for creation
email	string <email> Example: email=user@example.org Default email to propose to user for creation
back	string <uri> Example: back=https://example.org/cozy URL to go back for the first onboarding stage
source	string
redirect	string URL to go to after the creation, mainly for mobile onboarding. Will be completed with `fqdn` and `registerToken` in query parameters.
	object Informations used to create the account. Please note that the JSON object must be URL encoded, like: `?konnectors=%7B%22dummy%22%3A%7B%22account_type%22%3A%22dummy%22%2C%22auth%22%3A%7B%22id%22%3A%22someuserlogin%22%2C%22secret%22%3A%22pahNaPaloth0faingiichaic%22%7D%2C%22trigger%22%3Atrue%2C%22exec%22%3Atrue%7D%7D`. If several accounts must be created for the same konnector, it is possible to use an array of objects for them. It is possible to create aggregator accounts, like: `?konnectors=%7B%22aggregator%22%3A%7B%22id%22%3A%22dummy-aggregator%22%2C%22auth%22%3A%7B%22id%22%3A%22someuserlogin%22%2C%22secret%22%3A%22pahNaPaloth0faingiichaic%22%7D%2C%22trigger%22%3Afalse%2C%22exec%22%3Afalse%7D%7D`.
	object

Responses

createInstanceV1

Create an instance

Authorizations:

token

Request Body schema: application/json

offer required	string
slug required	string
domain required	string
aliases	Array of strings
email required	string <email>
public_name	string
locale	string
oidc	string OIDC sub to associate with the created Cozy for future OAuth authentication
	object
redirect	string URL to go to after the creation, mainly for mobile onboarding. Will be completed with `fqdn` and `registerToken` in query parameters.
	object

Responses

Request samples

Payload

Content type

application/json


{"offer": "cozy_default",
"slug": "foo",
"domain": "example.org",
"email": "foo@example.org",
"aliases": 
["bar.example.net",
"quz.example.org"
],
"public_name": "foo bar",
"locale": "fr",
"tos": 
{"version": "1.0.0",
"ip": "::1"
},
"oauth": 
{"client_name": "drive",
"software_id": "github.com/cozy/cozy-drive",
"redirect_uri": "http://localhost/oauth/callback",
"scopes": 
["read write"
],
"onboarding": 
{"app": "drive",
"state": "state",
"secret": "ed845b8839b99772d0e7",
"permissions": 
["read"
]
}
}
}

Response samples

200

Content type

application/json


{"_id": "f5134920-286d-49ef-8617-cc45e4d99c9a",
"workflow": "66f7ffd6-bad9-45ab-b49c-7fee4da89c70"
}

getInstanceV1

Fetch instance informations

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

Response samples

200

Content type

application/json


{"_id": "f5134920-286d-49ef-8617-cc45e4d99c9a",
"fqdn": "foo.example.org",
"aliases": 
["bar.example.net",
"quz.example.org"
],
"stack": "ovh-prod",
"activation": 
{"secret": "92a79b94b75e6eb2cc8a"
},
"state": "activated",
"created_at": "2022-06-30T15:16:17.852Z",
"updated_at": "2022-07-08T16:08:54.672Z",
"deleted_at": null
}

deleteInstanceV1

Delete an instance

Authorizations:

token

path Parameters

uuid

required

string <uuid>

query Parameters

user_request	boolean Default: true Flag the deletion as user requested
date	integer UNIX timestamp for planned deletion

Responses

Response samples

200

Content type

application/json


{"workflow": "e24770d6-20af-4f87-b4f4-2817e5868d39"
}

recreateInstanceV1

Recreate an instance

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

Response samples

200

Content type

application/json


{"workflow": "b1a943ab-7112-448e-83fd-f91dd73dff79"
}

blockInstanceV1

Block/unblock an instance

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Request Body schema: application/json

blocked

boolean

Default: true

Responses

Request samples

Payload

Content type

application/json


{"blocked": true
}

resendActivationEmailV1

Resend activation email for an instance

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

searchInstancesV2

Search for instances

Authorizations:

token

query Parameters

skip	integer >= 0 Default: 0 Skip n items (pagination)
limit	integer [ 0 .. 1000 ] Default: 1000 Limit result to only the first n items (pagination)
only	Array of strings Output only the given fields
exclude	Array of strings Exclude the given fields from the output
	object Example: fqdn=foo.example.org Filter instances on the given attributes values You can filter on timestamp field (`xxx_at`) presence with a boolean filter (`xxx: true\|false`)

Responses

Response samples

200

Content type

application/json


{"count": 247,
"limit": 10,
"skip": 30,
"items": 
[
{"_id": "f5134920-286d-49ef-8617-cc45e4d99c9a",
"fqdn": "foo.example.org",
"aliases": 
["bar.example.net",
"quz.example.org"
],
"activation": 
{"secret": "92a79b94b75e6eb2cc8a"
},
"state": "activated",
"created_at": "2022-06-30T17:18:19.654Z",
"updated_at": "2022-07-15T06:07:08.852Z",
"deleted_at": null
}
]
}

workflows

Workflows are used for asynchronous operations that can take some time to finish. They are composed of several steps, called jobs.

getWorkflowV1

Returns single workflow details.

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

Response samples

200

Content type

application/json


{"name": "CreateInstanceWorkflow-985589a3-071e-4bd1-94f4-9748a39d9a8d",
"started_at": "2022-06-30T15:16:45.962Z",
"finished_at": "2022-06-30T15:17:56.545Z",
"status": "succeeded",
"jobs": 
[
{"name": "WaitForDNS|095616a5-73e2-49f3-8529-5c6e7d586e77",
"queue": "backend",
"enqueued_at": "2022-06-30T15:16:46.003Z",
"started_at": "2022-06-30T15:16:46.102Z",
"finished_at": "2022-06-30T15:16:49.962Z",
"failed_at": null,
"error": null
},
{"name": "CreateInstance|c959777b-9436-43dc-bbe3-8006b3a72852",
"queue": "backend",
"enqueued_at": "2022-06-30T15:16:49.983Z",
"started_at": "2022-06-30T15:16:05.057Z",
"finished_at": "2022-06-30T15:16:50.685Z",
"failed_at": null,
"error": null
},
{"name": "IssueCertificate|56e0b5a5-9e7e-4e4e-84ee-b04db2e1a3e0",
"queue": "backend",
"enqueued_at": "2022-06-30T15:16:50.753Z",
"started_at": "2022-06-30T15:16:50.862Z",
"finished_at": "2022-06-30T15:17:51.863Z",
"failed_at": null,
"error": null
},
{"name": "SendActivationEmail|061ee259-cd5a-4a35-a7e9-001dbc1effa7",
"queue": "backend",
"enqueued_at": "2022-06-30T15:17:51.906Z",
"started_at": "2022-06-30T15:17:52.621Z",
"finished_at": "2022-06-30T15:17:56.489Z",
"failed_at": null,
"error": null
}
],
"errors": [ ]
}

restartWorkflowV1

Restart the given workflow

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

listWorkflowsV2

Fetch workflows associated to an instance

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

Response samples

200

Content type

application/json


[
{"id": "643dec40-ca66-40f4-aa66-20ea02443b98",
"class": "CreateInstanceWorkflow",
"created_at": "2021-11-10T10:23:48.359Z"
},
{"id": "195052a1-f2bb-4da2-aafd-12d3a3dea5d9",
"class": "RecreateInstanceWorkflow",
"created_at": "2021-11-10T10:46:18.353Z"
},
{"id": "a1a1b7de-a966-452d-8b75-74d5b2bc6002",
"class": "DeleteInstanceWorkflow",
"created_at": "2021-11-10T10:46:46.593Z"
},
{"id": "ad486f9c-fad8-4d84-a5fe-9cb8395413da",
"class": "RecreateInstanceWorkflow",
"created_at": "2021-11-10T10:46:51.642Z"
},
{"id": "024bfb3e-4190-486f-84aa-7a4beebe85d4",
"class": "DeleteInstanceWorkflow",
"created_at": "2021-11-10T15:16:03.682Z"
},
{"id": "03bd794b-4f73-4662-aa6b-2fa25dbc5371",
"class": "CreateInstanceWorkflow",
"created_at": "2021-11-10T15:16:09.660Z"
},
{"id": "90485eff-00f9-4841-9ab7-70e7001b6746",
"class": "DeleteInstanceWorkflow",
"created_at": "2021-11-16T09:38:19.785Z",
"status": "finished"
},
{"id": "b7482429-d84d-4a22-ba1e-f4b42a98b32c",
"class": "CreateInstanceWorkflow",
"created_at": "2021-11-16T09:38:26.143Z",
"status": "finished"
}
]

public

Endpoints that can be called from a mobile app (with a public token)

createInstancePublic

Create an instance

Authorizations:

token

Request Body schema: application/json

offer	string
slug	string
domain	string
aliases	Array of strings
email	string <email>
public_name	string
locale	string
oidc	string OIDC sub to associate with the created Cozy for future OAuth authentication
	object
redirect	string URL to go to after the creation, mainly for mobile onboarding. Will be completed with `fqdn` and `registerToken` in query parameters.
	object

Responses

Request samples

Payload

Content type

application/json


{"offer": "cozy_default",
"slug": "foo",
"domain": "example.org",
"email": "foo@example.org",
"aliases": 
["bar.example.net",
"quz.example.org"
],
"public_name": "foo bar",
"locale": "fr",
"tos": 
{"version": "1.0.0",
"ip": "::1"
},
"oauth": 
{"client_name": "drive",
"redirect_uri": "http://localhost/oauth/callback",
"software_id": "github.com/cozy/cozy-drive",
"scopes": 
["read write"
],
"onboarding": 
{"app": "drive",
"state": "state",
"secret": "ed845b8839b99772d0e7",
"permissions": 
["read"
]
}
}
}

Response samples

200

Content type

application/json


{"instance": "f5134920-286d-49ef-8617-cc45e4d99c9a",
"workflow": "66f7ffd6-bad9-45ab-b49c-7fee4da89c70"
}

sendReminderPublic

Send a reminder email if instance matching the given email

Authorizations:

token

query Parameters

email

required

string <email>

Example: email=foo@example.org

Responses

createDriveTokenPublic

Create a token with permissions for the files (drive)

Authorizations:

token

Responses

Response samples

200

Content type

application/json


{"token": "eyJH....x7kg"
}

getWorkflowPublic

Returns single workflow status

Authorizations:

token

path Parameters

uuid

required

string <uuid>

Responses

Response samples

200

Content type

application/json


{"status": "finished"
}

features

Feature flags

modifyFeatureFlagsV1

Modify feature flags for an instance

Authorizations:

token

path Parameters

uuid

required

string <uuid>

query Parameters

features

string

Example: features={"blockTransfer": true}

Features to set. If you give a null value, the flag will be removed. Field value must be a valid JSON string, properly URL encoded if needed.

Responses

Response samples

200

Content type

application/json


{"blockTransfer": true
}

getFeatureFlagsV1

Get the feature flags for an instance

Authorizations:

token

query Parameters

sets	string Example: sets=plan1,plan2 List of the feature sets of an instance (comma separated).

Responses

Response samples

200

Content type

application/json


{"flags": 
{"nb_connectors": 10,
"search": true
}
}

searchInstancesByFeatureFlagsV1

Search for instances having the given feature flags

Authorizations:

token

query Parameters

skip	integer >= 0 Default: 0 Skip n items (pagination)
limit	integer [ 0 .. 1000 ] Default: 1000 Limit result to only the first n items (pagination)
features	string Example: features={"blockTransfer": true} Features to select. Field value must be a valid JSON string, properly URL encoded if needed.

Responses

Response samples

200

Content type

application/json


{"count": 247,
"limit": 10,
"skip": 30,
"items": 
[
{"uuid": "e93154bc-fbac-4bef-9f0c-41829944d199",
"fqdn": "foo.example.org",
"partner": "cozy",
"offer": "cozy_default",
"context": "cozy_beta"
},
{"uuid": "65ff2ea0-a7ee-477b-80a9-1b8d48e81ecd",
"fqdn": "bar.example.org",
"partner": "cozy",
"offer": "cozy_default",
"context": "cozy_beta"
}
]
}

receiveAppStoreNotificationV2

Receive an App Store notification

Authorizations:

token

path Parameters

partner

required

string

Request Body schema: application/json

0

any

Responses

Request samples

Payload

Content type

application/json


{"0": null
}