Difference between revisions of "API Upload Project Assets"

From zFairs Contest Management
(Document image and paperwork upload)
Line 1: Line 1:
−
== Upload Project Assets ==  
+
== Upload Project Assets ==
 +
Upload project images/assets or paperwork files to an existing project.
  
−
=== Upload Project Image ===
+
=== Authentication ===
−
You can use our API to upload images to a project, so these can be viewed by your judges or in the showcase. To do this, you need to POST a message to your site. Below is an example of what needs to be posted.
+
All data API calls are <code>POST</code> (unless noted) with JSON body:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! Field !! Required !! Description
 +
|-
 +
| <code>ApiKey</code> || Yes* || Private API key for your site. Prefer this over username/password.
 +
|-
 +
| <code>Username</code> / <code>Password</code> || Yes* || Alternate auth if not using ApiKey.
 +
|-
 +
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
 +
|-
 +
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> when no body fields are needed.
 +
|}
 +
 
 +
* Provide '''either''' <code>ApiKey</code> '''or''' <code>Username</code>+<code>Password</code>.
 +
 
 +
Calls must be run '''server-side''' — do not expose your API key in a browser.
 +
 
 +
=== Response envelope ===
 +
Most endpoints return:
 +
 
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,  // error text when Success is false
 +
  Body: { ... }    // endpoint-specific payload
 +
}
 +
</pre>
 +
 
 +
 
 +
=== Upload project image / asset ===
 +
POST <code>/api/data/project/file</code>
  
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/project/file', {
 
fetch('/api/data/project/file', {
 
     method:'POST',
 
     method:'POST',
Line 11: Line 43:
 
     body: JSON.stringify({
 
     body: JSON.stringify({
 
             ApiKey:'<Private key>',
 
             ApiKey:'<Private key>',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
 
             Body: {
 
             Body: {
−
"ProjectKey":"32161f13-474b-442f-ac1f-edca7348e000",
+
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
−
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
+
Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
−
"DownloadFromUrl":"http://yoursite.com/somefile.png", //optional can be used in stead of Base64String
+
DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
−
"FileName": "myAwesomeFile.png",
+
FileName: "myAwesomeFile.png",
−
"Caption": "indescribable"
+
Caption: "indescribable"
 
}
 
}
 
         })
 
         })
Line 24: Line 56:
 
.then(data=>{console.log('Success: ',data);})
 
.then(data=>{console.log('Success: ',data);})
 
.catch((error)=>{console.log('Error: ', error);});
 
.catch((error)=>{console.log('Error: ', error);});
−
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
=== Upload Project Paperwork  ===  
+
=== Upload project paperwork ===
−
You can use our API to upload project paperwork, so these can be viewed by your judges, SRC, and IRB. These files need to be PDFs. You will need to get the PaperworkFileType form the [[API Get Info]]. To do this, you need to POST a message to your site. Below is an example of what needs to be posted.
+
Same endpoint. Paperwork should be PDF. Set <code>PaperworkFileType</code> from [[API Get Info]] → <code>PaperworkFileTypes</code>.
  
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/project/file', {
 
fetch('/api/data/project/file', {
 
     method:'POST',
 
     method:'POST',
 
     headers:{'Content-Type': 'application/json'},
 
     headers:{'Content-Type': 'application/json'},
 
     body: JSON.stringify({
 
     body: JSON.stringify({
−
             Username:'admin username',
+
             ApiKey:'<Private key>',
−
            Password: 'password',
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
 
 
             Body: {
 
             Body: {
−
"ProjectKey":"32161f13-474b-442f-ac1f-edca7348e000",
+
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
−
"PaperworkFileType": 123, // this is pulled from the get info api
+
PaperworkFileType: 123,
−
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
+
Base64String: "JVBERi0xLjQK...",
−
"DownloadFromUrl":"http://yoursite.com/somefile.png", //optional can be used in stead of Base64String
+
DownloadFromUrl: null,
−
"FileName": "myAwesomeFile.png"
+
FileName: "form1c.pdf",
 +
Caption: "Form 1C"
 
}
 
}
 
         })
 
         })
Line 51: Line 81:
 
.then(data=>{console.log('Success: ',data);})
 
.then(data=>{console.log('Success: ',data);})
 
.catch((error)=>{console.log('Error: ', error);});
 
.catch((error)=>{console.log('Error: ', error);});
 +
</syntaxhighlight>
  
−
</syntaxhighlight>
+
=== Response ===
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
 +
}
 +
</pre>
 +
 
 +
If the project key is invalid:
 +
 
 +
<pre>
 +
{ Success: false, Message: "Project not found with ProjectKey: ..." }
 +
</pre>
  
 +
=== Field notes ===
 +
* Provide '''either''' <code>Base64String</code> '''or''' <code>DownloadFromUrl</code>.
 +
* When <code>PaperworkFileType</code> &gt; 0, the file is stored as paperwork; otherwise as a project asset/image.
 +
* Uploaded files appear on [[API Get Projects]] under <code>projectFiles</code> / <code>paperworkFiles</code> with a <code>/file/showfile/{publicId}</code> path.
  
 +
=== Related APIs ===
 +
* [[API Get Projects]]
 +
* [[API Get Info]]
 +
* [[API Add Project]] / [[API Update Project]]
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Revision as of 12:49, 25 July 2026

Upload Project Assets

Upload project images/assets or paperwork files to an existing project.

Authentication

All data API calls are POST (unless noted) with JSON body:

Field Required Description
ApiKey Yes* Private API key for your site. Prefer this over username/password.
Username / Password Yes* Alternate auth if not using ApiKey.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.
  • Provide either ApiKey or Username+Password.

Calls must be run server-side — do not expose your API key in a browser.

Response envelope

Most endpoints return: 

{
  Success: true,
  Message: null,   // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}


Upload project image / asset

POST /api/data/project/file 

fetch('/api/data/project/file', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
				Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
				DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
				FileName: "myAwesomeFile.png",
				Caption: "indescribable"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Upload project paperwork

Same endpoint. Paperwork should be PDF. Set PaperworkFileType from API Get Info → PaperworkFileTypes. 

fetch('/api/data/project/file', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
				PaperworkFileType: 123,
				Base64String: "JVBERi0xLjQK...",
				DownloadFromUrl: null,
				FileName: "form1c.pdf",
				Caption: "Form 1C"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

{
  Success: true,
  Message: null,
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
}

If the project key is invalid: 

{ Success: false, Message: "Project not found with ProjectKey: ..." }

Field notes

  • Provide either Base64String or DownloadFromUrl.
  • When PaperworkFileType > 0, the file is stored as paperwork; otherwise as a project asset/image.
  • Uploaded files appear on API Get Projects under projectFiles / paperworkFiles with a /file/showfile/{publicId} path.

Related APIs



Retrieved from "https://wiki.zFairs.com/index.php?title=API_Upload_Project_Assets&oldid=946"