...
Use this API method to create a new document or folder. The result is in JSON format and contains the list of attributes of the newly created document.
Request URL
The request URL takes the following form:
POST <ROOT>/rest/stonikbyte-documents-api/1.0/document?projectId={projectID}
Parameters
Parameter | Description |
|---|---|
projectId | The id of the Jira project where the document will be created |
A successful response
An HTTP 200 status response indicates a successful request. Here is an example of data returned in JSON format:
| Code Block | ||
|---|---|---|
| ||
{
"versionNumber": 2,
"title": "Market Requirements Document",
"originalFileName": "mrd.docx",
"originalFileExtension": "docx",
"fileSize": 1541093,
"target": "5803722147480494253",
"description": "This document describes the market requirements.",
"currentRevision": "1.0",
"revisionAuthor": "John Smith",
"revisionDate": "2019-01-20 00:00:00.0",
"revisionNotes": "First Draft",
"createdBy":"admin",
"dateCreated": "2019-01-22 06:30:36.0"
} |
Depending on the document type, one of more attributes will be present in the result. Only the attributes with a value set will be returned.
...
Data
...
Description
...
Example
...
versionNumber
...
The version number
...
2
...
title
...
Also, the body of the request must contain a JSON with the attributes of the file.
Some of the attributes are required, depending on the document type.
Data | Description | Example |
|---|---|---|
type | Required. The type of the document. | "File" |
parentId | The ID of the folder where the document will be created. If not specified, the document will be created in the root folder of the specified Jira project. | 1 |
title | Required. The Title of the document. | "Market Requirements Document" |
originalFileName | Required for documents of type File. The name of the attached file. |
"mrd.docx" |
originalFileExtension
uploadedFileID | Required for documents of type File. To obtain the ID you have to upload the file first - see Uploading a file attachment section below | " |
fileSize
targetURL | Required for documents of type |
URL. |
target
The |
target URL for documents of type URL. |
description | The Description of the document. | "This document describes the market requirements." |
currentRevision | The Current Revision field of the document |
. | "1.0" |
currentRevisionDescription | The Revision |
Notes field of the document |
. | " |
First draft" |
currentRevisionAuthors | The Revision |
Author(s) field of the document |
. | " |
John Smith" |
currentRevisionDate | The Revision Date field of the document. It must be in YYYY-MM-DD format. | " |
2016- |
createdBy
The Jira user who actually created this version in the Jira system
"admin"
dateCreated
The date when the version was created in the Jira system
"2019-01-22 06:30:36.0"
...
12-25" |
Example of JSON body for creating a folder:
| Code Block | ||
|---|---|---|
| ||
{
"title": "Templates",
"type" : "Folder"
} |
Example of JSON body for creating a document of type File:
| Code Block | ||
|---|---|---|
| ||
{
"title": "Architectural Guidelines",
"type" : "File",
"originalFileName": "Architectural_Guidelines.pdf",
"uploadedFileID" : "9126255659437090493"
} |
Example of JSON body for creating a document of type URL:
| Code Block | ||
|---|---|---|
| ||
{
"title": "Company Web Site",
"type" : "URL",
"targetURL" : "https://stonikbyte.com"
} |
A successful response
An HTTP 200 status response indicates a successful request. The result in JSON format will contain the list with the attributes of the newly created document. See Obtaining the attributes of a document for a description of these attributes.
Error Response
If the REST call fails, the service returns one of the following HTTP statuses:
HTTP Status Code | Description |
|---|---|
401 Unauthorized | Returned for unauthenticated requests or in case of invalid Documents app license |
403 Forbidden | If the user does not have View permissions over the documentCreate permissions |
400 Bad Request | In case of invalid parameters. |