I recently tried to import Solutions and was informed by support that my problem was that tags were required.  A useful error message isn't provided I believe you get an error 500.

Short term suggestions for the API docs:

1. Make it clear that tags are required.  Since you don't require them in the interface, one would assume they wouldn't be required in the API.

2. Explain what artType is.  1 = Permanent 2 = Workaround, etc.

3. Explain the values for status: 1 = Draft 2 = Published

4. Add a curl example to the general page.

5. Include the raw headers that are expected... this can be generated by doing curl -v that would really help people in seeing what they're doing wrong as they could look at what their programming language was doing and compare to the raw headers to determine the problem.

Long Term API changes:

The API is a little confusing... not sure why it was designed that way...

1. Weird that a required field would be passed in as a get param.  Seems like this should be part of the body.

2. It's also strange that you have to specify the folder id as part of the XML... It's already in the path.

3. Allow the user to specify the name of the Category and folder instead of an ID.  This makes writing an import tool much more of a headache.

4. Once you've done that... I'd suggest allowing adding a new get param ?createCategory=true&createFolder=true.

That way you could create the folder and category if they don't already exist.  It'd make writing a simple import tool take minutes instead of hours.

I'll post some curl examples and add a link to a github project i'm working on later.