This article offers an in-depth overview of Craft's API capabilities*, specifically focusing on Workspace, Portfolio, and Feedback Portal operations. The flexibility of our APIs empowers you to seamlessly integrate information from Craft.io into a diverse range of systems and services, such as Business Intelligence (BI) tools, organizational communication channels, customer portals, support and customer success services, and reporting mechanisms.
(*) Public APIs are accessible to Enterprise customers only.
(*) The existing set of APIs is currently in the beta stage.
More in-depth information and a ‘try it out’ capabilities can be found in our API page.
API Use Cases
Among the data points that are accessible throughout our APIs are:
For workspace and portfolio:
List of workspaces of an account
List of portfolios of an account
Workspace’s terminology, including custom one
Portfolio’s terminology, including custom one
List of a workspace’s custom fields (name, id, category)
List of a portfolio’s custom fields (name, id, category)
Full work items’ metadata values, including custom fields. Work items are considered to be any variation of Initiative, Product, Epic, Feature and Story
For feedback portal:
Submitting a new feedback item, comprising a title, description, category, and submitter
List of feedback portals of an account
List of feedback portal categories
Full feedback items’ metadata values
By utilizing these APIs you can streamline processes, enhance data-driven decision-making, and create more interconnected workflows across your ecosystem.
Integration PreRequisites
To begin utilizing the powerful capabilities of our public APIs, you will need specific information to authenticate your requests. This includes:
Account API Key: Your account's API key serves as the authentication mechanism, verifying your access rights and enabling you to securely retrieve and manipulate your data.
Craft.io Account ID: This unique identifier associates your API requests with your Craft.io account, enabling secure and tailored access to your data.
Craft.io Workspace/Portfolio/Feedback Portal IDs: The IDs of the workspaces and portfolios you want to interact with. These IDs ensure that your API calls target the precise data you need.
To obtain these essential details, kindly reach out to your dedicated Customer Success Manager. They possess the expertise to provide you with the necessary information, ensuring a seamless integration of our APIs into your workflow.
Endpoints
More in-depth information and a ‘try it out’ capabilities can be found here.
Workspace Endpoints:
GET /workspaces/{accountId}
Retrieve the list of workspaces associated with your account.
Response: Workspace ID and name for each workspace.
GET /workspace/{workspaceId}/custom_fields
Retrieve the list of custom fields and their metadata for a specific workspace.
Response: Metadata for each custom field in the workspace.
GET /workspace/{workspaceId}/terminology
Retrieve the terminology used for entities within a workspace.
Response: List of terminology items.
GET /workspace/{workspaceId}/items
Retrieve metadata for all work items within a specific workspace.
Response: Metadata for each work item in the workspace.
GET /item/{itemId}
Retrieve metadata for a specific work item using its unique ID.
Response: Metadata for the requested work item.
Portfolio Endpoints:
GET /portfolios/{accountId}
Retrieve the list of portfolios associated with your account along with the workspaces they are connected with.
Response: Portfolio ID, name, and connected workspace information for each portfolio.
GET /portfolio/{portfolioId}/portfolio_fields
Retrieve the list of portfolio fields and their metadata for a specific portfolio.
Response: Metadata for each portfolio field in the portfolio.
GET /portfolio/{portfolioId}/terminology
Retrieve the terminology used for entities within a portfolio.
Response: List of terminology items specific to the portfolio.
GET /portfolio/{portfolioId}/items
Retrieve metadata for all initiatives within a specific portfolio.
Response: Metadata for each initiative in the portfolio.
GET /portfolio_item/{itemId}
Retrieve metadata for a specific portfolio item using its unique ID.
Response: Metadata for the requested portfolio item.
Feedback Portal Endpoints:
GET /feedback_portals/{accountId}
Retrieve the list of Feedback Portals associated with your account.
Response: Feedback Portal ID and name for each Feedback Portal.
GET /feedback_portal/{portalId}/categories
Retrieve the list of categories for a specific Feedback Portal.
Response: ID and name of each category of the Feedback Portal.
POST /feedback_portal/{portalId}/plain_feedback
Submit a brand new plain feedback item to your Feedback Portal. Plain feedback stands for title, description and category.
Response: General reference to the submitted feedback, such as ID and link.
GET /feedback_portal/{portalId}/feedback_items
Retrieve metadata for all feedback items within a specific Feedback Portal.
Response: Metadata for each feedback item in the Feedback Portal.
GET /feedback_item/{ideaId}
Retrieve metadata for a specific feedback item using its unique ID.
Response: Metadata for the requested feedback item.
API documentation page (Swagger)
For further information, including a ‘try it out’ capabilities, please visit our API documentation page (Swagger)
Beta Grade Disclaimer
Our beta-grade APIs are designed to give you early access to our evolving features and functionalities. While these APIs are tested and functional, they are still in active development. This means that there might be occasional updates, refinements, and changes to the API endpoints, structures, or workflows. We are committed to maintaining backward compatibility as much as possible, but it's important to be aware that some adjustments might be necessary as the APIs progress towards their stable version.
Change Log and Backward Compatibility
We understand the critical importance of maintaining a stable development environment. Any changes to the APIs will be diligently documented in our change log, highlighting modifications, additions, and deprecations. We are dedicated to providing detailed information about each change and its potential impact on existing integrations. Our team strives to ensure backward compatibility whenever feasible, minimizing disruptions to your current implementations.