A collection of available REST endpoints scoped to your unique instance. 

## ZUID
All named resources in this API have a unique identifier called a ZUID. For example an instance ZUID would like `8-f48cf3a682-7fthvk`. The initial prefix, e.g. `8-`, represents the type of resource it is. Every discreet resource has it's own prefix. To find a full list of supported ZUIDs and to learn more read the spec; https://github.com/zesty-io/zuid-specification

## URLs
As you peruse the available endpoints you will see the URLs which can be requested. The following is an explanation of the URL structure and the significance of specific portions.

For example the URL `https://8-f48cf3a682-7fthvk.api.zesty.io/v1/content/models/6-556370-8sh47g/items/7-b939a4-457q19/publishings/18-660e14-jpx715` would breakdown as follows;

| https:// | 8-f48cf3a682-7fthvk | .api.zesty.io/ | v1 | /content/models/6-556370-8sh47g | /items/7-b939a4-457q19 |/publishings/18-660e14-jpx715 |
| :-------------: | :----------: | :-------------: | :----------: | :-------------: | :----------: | :-------------: |
| protocol | Your instances unique identifier | domain for the API | version of the API | path to a unique content model | path to a unique item which belongs to the prior model | path to a unique publishings record which belongs to the prior item |

## Getting an Auth Token
There are two types of authorization; session and access tokens. Read more about them here https://zesty.org/apis/auth-api#user-authentication

Instances API

# Content 

Namespace that collects all the named resources that modify content in the Zesty.io Instance. This includes content models, content model fields, content items, content model triggers, can content languages (internationalization).


/content/links

Content models are user defined structures setup to handle custom content entry, editing, and access. They have the option to connect to www services or to be stand alone content access through headless endpoints. Content Models have fields and content items. Content Model Fields are also user defined, so users can create any structure to store, create, and edit content. Content Items are content entries that are entered to match the custom fields on teh collection setup by the user.

Content Models may be parented to eachother for use of interface layout, but this connection does not current change behavior of access or permissions.

Content Models may only be edited by their owner or a user with admin or developer permissions.


*Routes and Views*

Content Models have the option to have a view associated with them. When this happens, each of the collections contents have routes associated with them. Routes can be acessed as `path_full` and `path_part`. Full paths of routes are generated based on the contents parent, and its parent. The parent of the collection does not affect the full path.


*Settings*
settings[defaultRSS] = boolean


*Scaffolding*
Future Feature, stores the default HTML layout of the view

/content/models

Model Fields are user defined fields on a content model. They allow users to create their own content editing experiences by defining custom input interfaces. Model Fields are unique to their respective model and cannot be shared. Model fields do have a unique ZUID, which always start with **12** e.g. `12-57d5ab3-89tfj1`

Each field has a type, each type has unique attributes to control content entry behaviors.

##### Field Data Types: 
* **[article_writer]**
* **[brandisty]**
* **[color]**
* **[currency]**
* **[date]** Stores a simple date, data sent in the format YYYY-MM-DD
* **[datetime]** Stores a timestamp accepts data in the format YYYY-MM-DD HH:II:SS
* **[dropdown]** creates a pre-populated dropdown controlled by the (options)
* **[files]** Accepts uploads to media and store the file references (requires the field type option `limit`)
* **[fontawesome]**
* **[images]** An images field (requires the field type option `limit`)
* **[internal_link]** A field that accepts a Content ZUID and auto generates a link
* **[link]** A field that should validate a hyperlink url
* **[markdown]** Stores and interprets markdown
* **[number]** Number looks for any int or double
* **[one_to_many]** One to many Relationship to another collection. *(requires relationship field on creation)*
* **[one_to_one]** One to one relationship to another collection *(requires relationship field on creation)*
* **[sort]** A sort order field
* **[text]** Text
* **[textarea]** Text Area 
* **[uuid]**
* **[wysiwyg_basic]** What you see is what you get Editor
* **[yes_no]** Yes/No fields take in two specific options

/content/models/fields

Content Items are rows of a Content Model

/content/models/items

/content/models/parsley-items

/content/models/items/batch

/content/models/items/versions

Publishing records is how the API represents when an items version should be public. These are records which are discreet from the content item record itself.

/content/models/items/publishings

/content/items/publishings

| name | type | required | example |
| --- | --- | --- | --- |
| `where` | string | false | `item.title = 'sometitle'` |
| `limit` | string | false | `2` for limit or `2, 2` for limit with offset |
| `sort` | string | false | `item.created_at DESC` |
| `_active` | boolean | false | `true` or `false` |

NOTE: The examples for where, limit, and sort are listed in plaintext but when the request is sent those query param values must all be base64 URL encoded.

Publish All Content

RPC (Remote Procedure Call) which will publish the latest version of all content items on an instance.
## Optional Language Variant
To publish all items of a language variant, add the "lang" query parameter to the request
- Example: lang=es-MX

Publish All Model Content

RPC (Remote Procedure Call) which will publish the latest version of all content items on a single instance model.

## Optional Language Variant
To publish all items of a language variant, add the "lang" query parameter to the request
- Example: lang=es-MX

/content

Resources that control and manipulate the presentaiton layer

/web/views

/web/redirects

/web/views/versions

/web/stylesheets

/web/stylesheets/variables

/web/stylesheets/variables/categories

/web/stylesheets/versions

/web/scripts

/web/scripts/versions

/web/headers

/web/headtags

/web

# Environment 

Named resources that are not used in day to day production but affect the overall experience of editing and management of named resources in an instance, are filed under the environment namespace.

Simple examples are Audit Logs and parented navigations. 

Settings are key value pairs datastore for controlling aspects of Zesty.io, such as creating extensions, controlling web engine behaviors, and changing user interface behaviors.

For example: 
- Turning off public endpoints
- Blocking access by IP address.

/env/settings

/env/nav

The Audit Trail acts as an immutable log of various actions taken on an instance by users. It is system controlled and as such does not allow for user creation or updating of logs.

/env/audits

/env/leads

Any instance can have multi-lang support. Once multi-lang is activated languages can be added. When a language is added it does not become immediately available. A separate request must be made to activate the specific language. This allows for a workflow of adding a language, creating content for the language and activating the language to make it public.

/env/langs

/env

This is a feature app containing a collection of items that are ready to be published which are grouped by `name` specified when creating a Release. Each Release can have multiple [Items](https://zesty.org/quick-start-guide/adding-content) called Members.

Activate Release

Enable/activate the `releases` feature - uncharacteristic for a POST, this endpoint is idempotent.

Create Release

Creates a new Release for this instance. You can add multiple Releases with multiple Release Members.

**Note**: You can only start adding Releases after activation. _See Activate Release_.

| **name** | **description** |
| --- | --- |
| `name` | \[`string`\] **Required**. Non-unique Display Name |
| `description` | \[`string`\] Additional context |

Get Releases

Retrieves all the Releases that has been added.

**Note**: Calling this method before activation will throw a `204` error code.

Get Release

Retrieve a specific Release based on the `release_zuid` provided.

**Note**: Calling this method before activation will throw a `204` error code.

Update Release

Updates a specific Release. The only updatable fields are `name` and `description`.

**Note**: Updating non-updatable fields results in a `200` and the response shows the field as being updated **BUT** a subsequent `GET` to the Release ZUID will show that the `PUT` did **NOT** take. This erroneous response will be fixed in future updates.

Calling this method before activation will throw a `204` error code.

Delete Release

Deletes a specific Release based on the `release_zuid` provided.

**Note**: Calling this method before activation will throw a `204` error code.

/releases

After activating and creating a Release object, you can start adding multiple [Items](https://zesty.org/quick-start-guide/adding-content), which are called Members, by specifying the Item's ZUID and version.

Create Release Member

Adds an Item to a specific Release by providing the Item's ZUID and version number.

| **name** | **description** |
| --- | --- |
| `resourceZUID` | \[`string`\] **Required**. Resource To Publish |
| `version` | \[`number`\] **Required**. Resource Version To Publish |

**Note**: Calling this method before activation will throw a `204` error code.

Get Release Members

Retrieves all Members of a specific Release.

**Note**: Calling this method before activation will throw a `204` error code.

Get Release Member

Retrieves a Member from a specific Release.

**Note**: Calling this method before activation will throw a `204` error code.

Update Release Member

Updates a specific Member. The only updatable field is `version`.

**Note**: Updating non-updatable fields results in a `200` and the response shows the field as being updated **BUT** a subsequent `GET` to the Resource ZUID will show that the `PUT` did **NOT** take. This erroneous response will be fixed in future updates.

Calling this method before activation will throw a `204` error code.

Delete Release Member

Deletes a specific Member.

**Note**: Calling this method before activation will throw a `204` error code.

/releases/members

Search

Allows searching for contents by either ZUID, meta text values or path-related values.

List of ZUID typees that will do the search into for 'q' value:

- Content Models
- Users
- Items
    

List of meta and path keys that will do the search into if 'q' value is not a ZUID:

- URL Path Part
- Full Path
- Navigation Link Text
- Meta Title
- Meta Description
- Meta Keywords

/search

Auth API is used to authenticate users with Zesty.io, which returns a token that grants to access  services like Instances API, Accounts API, and Media API. Auth was setup as a stand alone service so it can connect to many services in our infrastructure. 

Permissions are managed at the service level, for example, to manage permissions on instances, you would use the [Accounts API](https://accounts-api.zesty.io) to do so

Authentication API

Login

Log-in by authenticating a user with a user email and password. Five (5) failed login attempts will prevent login for 5 minutes.

Two Factor Authentication (2FA)

Two Factor Authentication (2FA) provides an additional layer of security. 2FA involves issuing a [One Time Password (OTP)](https://www.twilio.com/docs/authy/api/one-time-passwords).

With 2FA logging in means both the user credentials and access to a physical device which will issue a OTP is required. We use [authy.com](https://authy.com/) for handling 2FA and issuing OTP.

After a standard login with user credentials entering a OTP will be required. This can also be done manually via the Authy app or their [OneTouch](https://www.twilio.com/authy/features/push) feature. Once a valid OTP is provide login will finish and  application access will be granted.


Two Factor Authentication

Verify

Applications can use this API to periodically verify a session token is still valid.

Tokens expire 20 minutes from last login or API usage. Everytime an API call is run the session extends 20 minutes.

Logout

Sending a session token to this API will invalidate the provided token.

{
    "message": "",
    "status": "OK",
    "meta": {},
    "code": 200
}

API used to control management of users, roles, instances, and teams.

Accounts API

Create Instance

Creates an instance. This will automatically generate a new instance ZUID and the user making the Create Instance request will be set as the Owner.

Create Instance with an ecosystem ID

Verify DNS

Verifies a DNS record matches a CName or A record

Get Instance

Get All Instances

Get All Invited Instances

Gets all instances a user has been invited to.

Get Instance Users

Get Instance Users With Roles

Gets a single instance's users with their instance-based role attached.

Get Instance Pending Users

Get Instance Companies

Update Instance

Update permissions for a given user and content instance. Takes one of following values for the query param `action`.

- `updateEcosystem`
- `updateDomain`
- `updateBlueprint`
- `purgeCache`

Update Instance Blueprint

**Erases the current instance and replaces instance with the specified blueprint**

**Warning:** This is a destructive action and is **NOT** reversible.

Purge Instance

Update permissions for a given user and content instance. Takes one of following values for thea query param `action`.
- `updateEcosystem`
- `updateDomain`
- `updateBlueprint`
- `purgeCache`

Delete Instance

/instances

Create Domain

Get Domain

Get All Domains

Gets all domains associated with an instance.

Update Domain

Delete Domain

/instances/domains

Create User

Creates a single user. Returns hydrated user error.

Get User

Get User Instances

Update User

Delete User

/users

Add Unverified Email

Adds an email address as unverified; sends verification email

Resend Email Verification

Resends the email used for verifying an email address

Get User Emails

Verify Email Address

Delete User Email

Removes a verified or unverified email address.

/users/emails

Create Company

Get Company

Get All Companies

Delete Company

/companies

Create Invite

Get Invite

Get All Invites

Respond to Invite

Responds to an invite based on the query parameter provided. Takes one of following values for the query param `action`.
- `accept`
- `decline`
- `cancel`

Delete Invite

/invites

Create Blueprint

Get Blueprint

Get All Blueprints

Get Instance's Blueprint

Update Blueprint

Updates a blueprint with the given values.

Delete Blueprint

/blueprints

Create Team

Get Team

Get All Teams

Gets a all teams associated with the user.

Update Team

Delete Team

/teams

Add Team to Instance

Creates a single team and adds it to an instance.

Get All Instance's Teams

Gets all Teams associated with the Instance.

Get All Team's Instances

Gets a all Instances associated with the Team.

Remove Team from Instance

Removes a  ALL Team members from a given Instance.

/team/instances

Create Team Invite

Creates a single invite for the given Team

Get Team Invite

Get All Team Invites

Respond to Team Invite

Responds to a team invite based on the query parameter provided

- ?action=accept	:: Accept an invite.
- ?action=decline	:: Decline an invite.
- ?action=cancel	:: Cancel an invite; you must have sufficient privilege to perform this

Delete Team Invite

/teams/invites

Get Team Members

Update Team Member

Remove Team Member

Get Team Members Pending

Gets the pending members of a single Team

/teams/members

Create Role

Creates a role with the provided system role as its base.

Get Role

Get Roles

Gets all roles associated with the current user

Delete Role

Create Instance Roles

Get Instance Role

Get Instance Roles

Assign User Role

Adds an entry for the provided user and role ZUID.

Get User Roles

Update User Role

Updates the entry for the provided user and role ZUID with the `roleZUID` element in the request body. Fails if the user/role entry in the URL does not exist.

Delete User Role

/roles

Create Granular Role

Adds a granular role to the role with the given role ZUID.

StartFragment

In the body content, you can pass content models (schemas), instances, and item ZUID as the resource ZUID.

EndFragment